Storybook @bq/ui

Overview

Storybook @bq/ui is the working design system for Becoming Quotient, a live, code-backed source of truth for design tokens, themes, fonts, and component atoms → molecules → organisms. The brand aesthetic is 'Functional Clarity'—a minimalist, light-first approach that prioritizes developer ergonomics and accessibility without sacrificing visual refinement. The UI uses a cool, neutral palette anchored by a vivid cyan primary (#0a9cfd) that signals interactivity and trust, paired with a restrained gray-blue secondary (#73828c) for supporting elements. The emotional response is one of calm competence: users feel they're working with a mature, well-considered system.

The voice is precise, technical, and honest. Vocabulary favors concrete nouns (tokens, atoms, organisms, workspace) over marketing abstractions. Tone is never breathless or casual—it's the voice of an engineer explaining a well-designed API. Example sentence: 'The @bq/ui workspace holds design tokens, theme, fonts, and atoms → molecules → organisms component library, all on Tailwind v4 + shadcn/ui.'

Colors

The color system is built on a light, accessible foundation with a single, high-contrast primary accent. Primary (#0a9cfd, a vivid cyan) is reserved exclusively for interactive elements—buttons, links, focus states, and key CTAs. It appears sparingly but decisively, creating visual hierarchy without noise. Secondary (#73828c, a muted blue-gray) supports navigation, disabled states, and secondary text; it is never used for primary actions. Tertiary (#ff4785, a vibrant pink-red) is reserved for error states, alerts, and brand accent moments in marketing contexts—never for primary UI.

The surface stack is built on a light, cool background (#f6f9fc, rgb(246, 249, 252)) with a full range of container layers: surface-container-lowest (#f0f9fa) for subtle backgrounds, surface-container (#dfe3e8)

Typography

The type system uses Nunito Sans across all weights (400 regular, 700 bold) and styles (normal, italic), loaded via @font-face with font-display: swap for performance. Display (60px, 700, -0.04em letter-spacing) is reserved for hero headlines; Headline-lg (40px, 600, -0.02em) for major section breaks; Headline-md (28px, 600) for subsection titles. Body-lg (18px, 400) is used for introductory paragraphs and rich content; Body-md (16px, 400) is the default for body text and form labels. Label-md (14px, 600, 0.01em) is used for button text, form labels, and UI chrome; Label-sm (12px, 700, 0.05em) is used for badges, tags, and small UI hints. All type sizes use unitless line-height (1.5 for body, 1.2 for headlines) to scale proportionally with font size. Apply text-shadow: 0 1px 2px rgba(0, 0,

Layout

The layout uses a 12-column grid with a max-width of 1280px (container-max-width: 1280px). The sidebar is fixed at ~280px width; the main content area is fluid and responsive. Spacing follows a semantic scale: xs (4px) for micro-spacing within components, sm (12px) for padding inside cards and inputs, md (24px) for gutter spacing between sections and component padding, lg (40px) for major section separation, and xl (64px) for page-level spacing. The gutter (24px) is used consistently for left/right margins on the main content area. White-space is generous—cards and sections are separated by at least lg (40px) vertical spacing to create visual breathing room. Inputs and buttons use sm (12px) padding vertically and md (24px) horizontally; cards use md (24px) padding on all sides. The sidebar

Elevation & Depth

Elevation is conveyed through subtle shadows and background color shifts rather than dramatic depth. Level 1 (Base): the light background (#f6f9fc) with no shadow, used for the page canvas. Level 2 (Standard Card): background #ffffff with a 1px border in outline-variant (#b0b8c0) and box-shadow: 0 3px 8px rgba(0, 0, 0, 0.15), used for cards, dropdowns, and modals. Level 3 (Elevated/Hover): background surface-container-low (#e9ecef) with box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12), used for hovered cards and active dropdowns. All shadow transitions use 200ms ease-in-out timing. Focus states on i

Shapes

The shape philosophy is 'Soft-Technical'—rounded corners are used consistently but conservatively to signal interactivity without sacrificing the clean, professional aesthetic. Buttons and inputs use rounded.lg (1rem, 16px) for a soft, approachable feel; cards and panels use rounded.lg (1rem) for consistency. Dropdowns and tooltips use rounded.lg (1rem). Badges and tags use rounded.full (9999px) for a pill shape, signaling they are discrete, removable elements. The default rounded value (0.5rem, 8px) is used for minor UI elements like focus rings and small containers. No elements use sharp cor

Components

Action Elements Buttons are the primary interactive element. Button-primary uses background: {colors.primary} (#0a9cfd), text-color: white, padding: 10px 15px, height: 40px, rounded: 1rem, and label-md typography (14px, 600). On hover, the background shifts to #0080cc (a darker cyan) with a 200ms transition. Button-secondary uses background: rgba(115, 130, 140, 0.1) (a 10% tint of the secondary color), text-color: {colors.primary}, and a 1px border in outline-variant. On hover, the background becomes surface-container-high (#d0d0d0). Both button states include a focus ring: box-shadow: 0 0 0 3px rgba(10, 156, 253, 0.1).

Containers & Surfaces Cards are the primary container element. Card uses background: white, rounded: 1rem, padding: 24px, border: 1px solid {colors.outline-variant

Do's and Don'ts

**Do**

• Do use primary (#0a9cfd) exclusively for interactive elements—buttons, links, focus states, and CTAs. Never use it for backgrounds or decorative elements.
• Do apply a 200ms transition to all interactive state changes (hover, focus, active) to signal responsiveness without jarring the user.
• Do use the full surface-container stack to create visual hierarchy: lowest for subtle backgrounds, mid for cards, highest for pressed/active states.
• Do pair Headline-md (28px, 600) with Body-md (16px, 400) for section headers and body text; this pairing creates clear visual hierarchy without overwhelming.
• Do use md (24px) spacing for gutter and card padding; this creates a consistent, spacious rhythm across the interface.
• Do apply box-shadow: 0 3px 8px rgba(0, 0, 0, 0.15) to cards and dropdowns to create subtle depth without visual noise.

**Don't**

• Don't use primary (#0a9cfd) for body text, backgrounds, or decorative elements—reserve it exclusively for interactive CTAs and focus states.
• Don't apply rounded corners smaller than 0.5rem (8px) on interactive elements; this reduces perceived affordance and accessibility.
• Don't use secondary (#73828c) or tertiary (#ff4785) for primary actions; these colors are reserved for supporting roles and error states.
• Don't apply multiple shadows or nested elevation levels; stick to the three-level system (base, standard card, elevated) to avoid visual clutter.
• Don't use font-weight lighter than 400 or heavier than 700; Nunito Sans only supports these weights and mixing weights creates inconsistency.
• Don't apply letter-spacing greater than 0.05em on body text; this reduces readability. Reserve tight letter-spacing (-0.04em) for display headlines only.