Design System

A CSS-based design system with design tokens and reusable component classes. Use the tokens and crate-* classes in any project for consistent branding and UI.

Install from npm

npm install crate-design-system

Then load the stylesheets in your app (in this order):

<link rel="stylesheet" href="node_modules/crate-design-system/css/design-system.css" />
<link rel="stylesheet" href="node_modules/crate-design-system/css/components.css" />

Or with a bundler (Vite, Webpack, etc.):

import 'crate-design-system/css/design-system.css';
import 'crate-design-system/css/components.css';

Then use the tokens (var(--*)) and component classes (e.g. crate-btn, crate-btn--primary) in your HTML.

Quick start (without npm)

1. Copy the tokens/ and css/ folders into your project, or link to them.
2. Load the stylesheets in this order:

<link rel="stylesheet" href="path/to/css/design-system.css" />
<link rel="stylesheet" href="path/to/css/components.css" />

3. Use the tokens (var(--*)) and component classes (e.g. crate-btn, crate-btn--primary) in your HTML.

To preview the component showcase locally, run:

npm install
npm run preview

Then open http://localhost:3000/docs/index.html in your browser. Use the sidebar (on desktop) or the table of contents on the home page to jump to Foundations (colors, typography, spacing, radius, shadows, strokes, width), Atoms (icons, buttons, badges, dividers), Molecules (inputs, stepper & chips, alerts, cards, list items, nav bar), and Organisms (warehouse card, bottom sheet, progress steps, footer bar, page template, layout).

Load order

| Order | File | Purpose | |-------|------|---------| | 1 | css/design-system.css | Imports tokens, Lato font, base body styles, icon size utilities | | 2 | css/components.css | All crate-* component classes |

design-system.css imports tokens/design-tokens.css, so you only need to link the two CSS files above (tokens are pulled in automatically).

Design tokens

All tokens are defined in tokens/design-tokens.css and (for tooling/Figma) in tokens/Mode-1.tokens.json.

Spacing (4px base)

| Token | Value | |-------|--------| | --sp-0 | 0 | | --sp-1 | 0.25rem | | --sp-2 | 0.5rem | | --sp-3 | 0.75rem | | --sp-4 | 1rem | | --sp-5 | 1.25rem | | --sp-6 | 1.5rem | | --sp-8 | 2rem | | --sp-10 | 2.5rem | | --sp-12 | 3rem | | --sp-16 | 4rem | | --sp-24 | 6rem | | --sp-32 | 8rem | | --size-tap-target | 2.75rem (44px min for pointer targets) | | --size-input-min-height | 2.75rem | | --size-container-max | 75rem |

Border radius (squircle / One UI)

Use large radii for all interactive and container elements. Prefer --radius-xl and above for buttons, cards, inputs, modals.

| Token | Value | Use | |-------|--------|-----| | --radius-sm | 0.375rem | Minimal only (e.g. page indicator) | | --radius-md | 0.5rem | 8px | | --radius-lg | 0.75rem | Chips, small tags | | --radius-xl | 1rem | Inputs, icon boxes | | --radius-2xl | 1.25rem | Buttons, CTAs, nav bar | | --radius-3xl | 1.5rem | Cards, panels | | --radius-4xl | 2rem | Large cards, sheets | | --radius-full | 9999rem | Pill/capsule |

Typography

• Font family: --font-family (Lato + system fallbacks)
• Font sizes: --fs-xs (0.75rem) … --fs-4xl (2rem), including --fs-md, --fs-base, --fs-lg, --fs-xl, --fs-2xl, --fs-3xl
• Font weights: --fw-regular, --fw-medium, --fw-semibold, --fw-bold, --fw-extrabold
• Line heights: --lh-tight (1.25), --lh-normal (1.5)

Shadows

| Token | Use | |-------|-----| | --shadow-sm | Controls, chips, inputs | | --shadow-md | Cards, panels | | --shadow-lg | Modals, bottom sheets | | --shadow-xl | Overlays, snackbars | | --shadow-footer | Sticky footer bar |

Colors

• Primary: --color-primary-50 … --color-primary-900 (purple; 500 = #7957FF)
• Secondary: --color-secondary-50 … --color-secondary-900 (teal)
• Neutral text: --color-white, --color-text-25 … --color-text-900
• Navy: --color-navy-800, --color-navy-900 (dark UI)
• Traffic: Red, Orange, Green, Blue — each --color-{name}-50 … --color-{name}-900
• Accent yellow: --color-yellow-50 … --color-yellow-900
• Alert (legacy): --color-alert-bg, --color-alert-border, --color-alert-text

For dark neutrals (body text, borders, dark surfaces), use the text scale (--color-text-500 … --color-text-900) or navy for dark UI (--color-navy-800, --color-navy-900). Do not use a separate black palette.

Use var(--color-primary-500) etc. in your CSS. Do not change these tokens in the design system files.

Component classes

Buttons

• Base: crate-btn
• Variants: crate-btn--primary, crate-btn--secondary, crate-btn--ghost
• Sizes: crate-btn--sm, crate-btn--lg (default is medium)

Example: <button class="crate-btn crate-btn--primary">Save</button>

Cards

• crate-card, crate-card--bordered
• crate-card__title, crate-card__body

Alerts

• crate-alert + modifier: crate-alert--warning, crate-alert--success, crate-alert--error, crate-alert--info

Badges

• crate-badge + modifier: crate-badge--success, crate-badge--warning, crate-badge--error, crate-badge--primary, crate-badge--info, crate-badge--neutral

Form

• crate-input — text input
• crate-label — label above input
• crate-input-group — wrapper with margin

Typography

• Headings (use with semantic <h1>–<h6>): crate-heading-1 … crate-heading-6; crate-display (same as H1 for hero)
• Body & supporting: crate-text-body, crate-text-small, crate-text-caption, crate-text-overline, crate-text-muted
• Labels: crate-label (form labels)

Layout

• crate-container — max-width container with horizontal padding
• crate-stack, crate-stack--sm, crate-stack--lg — vertical stack with gap
• crate-row, crate-row--sm, crate-row--lg — horizontal row with gap

Divider

• crate-divider, crate-divider--tight

List

• List: crate-list — wrapper (<ul> or <div role="list">). Modifiers: crate-list--bordered (card-style border), crate-list--inset (grouped iOS-style).
• List item: crate-list-item — row with optional crate-list-item__lead (icon or avatar), crate-list-item__content, crate-list-item__title, crate-list-item__sub, crate-list-item__trail. Use crate-list-item__icon (with --secondary, --success, --warning, --error for color). Use <a> or <button> with crate-list-item for clickable rows.
• Simple row: crate-list-item--simple for text-only single-line items.

Nav bar

• crate-nav-bar, crate-nav-bar__title, crate-nav-bar__actions

Accessibility (WCAG)

The design system and docs are built with WCAG 2.1 (and 2.2 where applicable) in mind.

• Focus visible: Buttons, links, and inputs use :focus-visible with a visible outline or box-shadow (primary color, 2–3px) so keyboard users always see focus. outline: none is only used when replaced by a visible ring; file input, select, tabs, and pagination all have a visible focus indicator.
• Color contrast: Text tokens (--color-text-700, --color-text-900, etc.) on white backgrounds meet contrast requirements for body and heading text. Primary buttons use white text on --color-primary-500; secondary and ghost buttons use dark text on light backgrounds. For custom pairs, ensure at least 4.5:1 (normal text) or 3:1 (large text) for WCAG AA.
• Touch/tap targets: Interactive controls use at least 44×44 CSS pixels (WCAG 2.5.5 Level AAA). The token --size-tap-target (2.75rem) is used for pagination, tabs, rich-editor toolbar buttons, tag-input remove, and rating stars. Buttons use min-height: var(--sp-12) (3rem). Inputs use --size-input-min-height (2.75rem).
• Reduced motion: prefers-reduced-motion: reduce is respected: transitions and animations are minimized so users who prefer reduced motion are not distracted.
• Semantic HTML: Use <button> for actions, <a> for navigation, <label> with for/id for form fields. Pair component classes with the right elements and ARIA where needed (e.g. aria-label for icon-only buttons, role="tablist"/role="tab" for tabs).
• Docs: The documentation site includes a “Skip to main content” link, aria-current="page" on the active nav item, aria-label on nav and menu button, role="tooltip" where appropriate, and lang on the document.

When building with this system, ensure form inputs have visible labels (use crate-label with for pointing to the input id), and that icon-only controls have aria-label or aria-labelledby.

Tailwind

tailwind.config.js is provided as a preset that mirrors the design tokens (colors, spacing, radius, shadows, font). Use it in a Tailwind-based project by extending the theme. This repo does not run a Tailwind build; the design system is plain CSS.

Brand guidelines

See BRAND.md for usage rules and what not to change.

File structure

├── README.md           (this file)
├── BRAND.md            (brand guidelines)
├── package.json
├── .gitignore
├── tailwind.config.js  (Tailwind preset reference)
├── tokens/
│   ├── design-tokens.css   (CSS custom properties)
│   └── Mode-1.tokens.json  (Figma/tooling export)
├── css/
│   ├── design-system.css   (base: tokens, fonts, body)
│   └── components.css      (crate-* components)
└── docs/
    ├── index.html          (home + table of contents)
    ├── shared.css          (docs layout and showcase styles)
    ├── colors.html … layout.html  (one page per section)
    └── split-pages.js      (optional: re-split from single page)