@maxsteinwender/sort-ui 1.0.6 → 1.0.8

package/guidelines/styles.md

@@ -0,0 +1,356 @@
+# Style System Guidelines
+
+Spacing, layout, responsive patterns, and CSS methodology for SortUI.
+
+## CSS Methodology
+
+SortUI uses **Tailwind CSS v3** (`^3.4.1`). It is **NOT** Tailwind v4. The design system provides:
+
+1. **Design tokens** (CSS custom properties)
+2. **Tailwind v3 preset** (extends Tailwind with SUI tokens)
+3. **Component classes** (component-specific styles)
+
+**Never emit Tailwind v4 syntax** (`@theme` directive, v4-only APIs). Always author styles for Tailwind v3.
+
+---
+
+## Spacing Scale (WITH `sui-` prefix)
+
+SortUI uses a numeric spacing scale based on pixels. Use with `gap-`, `p-`, `m-`, `space-x-`, `space-y-`, etc.
+
+| Class | Size | Common Usage |
+|-------|------|--------------|
+| `gap-sui-none` | 0px | No spacing |
+| `gap-sui-1` | 1px | Hairline |
+| `gap-sui-2` | 2px | Minimal |
+| `gap-sui-4` | 4px | Extra small |
+| `gap-sui-6` | 6px | Small− |
+| `gap-sui-8` | 8px | Small |
+| `gap-sui-12` | 12px | Medium small |
+| `gap-sui-16` | 16px | Medium — form field gap |
+| `gap-sui-20` | 20px | Medium+ |
+| `gap-sui-24` | 24px | Large — card padding |
+| `gap-sui-32` | 32px | Section gap |
+| `gap-sui-40` | 40px | XXL |
+| `gap-sui-48` | 48px | XXXL |
+| `gap-sui-64` | 64px | Large sections |
+| `gap-sui-80` | 80px | Hero |
+| `gap-sui-96` – `gap-sui-384` | 96–384px | Page sections, hero spacing |
+
+**Usage:**
+```tsx
+<div className="p-sui-24" />        {/* padding: 24px */}
+<div className="m-sui-16" />        {/* margin: 16px */}
+<div className="gap-sui-12" />      {/* gap: 12px */}
+<div className="space-x-sui-8" />   {/* horizontal spacing */}
+<div className="space-y-sui-16" />  {/* vertical spacing */}
+```
+
+---
+
+## Common Spacing Patterns
+
+### Component Spacing
+
+| Pattern | Class |
+|---------|-------|
+| Input field padding | `px-sui-12 py-sui-10` |
+| Button padding (md) | `px-sui-12 py-sui-8` |
+| Button padding (lg) | `px-sui-16 py-sui-12` |
+| Card padding | `p-sui-24` |
+| Form field gap | `gap-sui-16` |
+| Section gap | `gap-sui-32` or `gap-sui-48` |
+| Page margins | `mx-sui-24` or `mx-sui-32` |
+
+### Layout Spacing
+
+| Context | Class | Rationale |
+|---------|-------|-----------|
+| Between form fields | `gap-sui-16` | Comfortable reading distance |
+| Between form sections | `gap-sui-32` | Clear visual grouping |
+| Card internal padding | `p-sui-24` | Balanced white space |
+| Modal/dialog padding | `p-sui-24` or `p-sui-32` | |
+| Navigation items | `gap-sui-8` or `gap-sui-12` | |
+
+**Example form spacing:**
+```tsx
+<form className="flex flex-col gap-sui-16">
+  <InputField label="Name" />
+  <InputField label="Email" />
+  <div className="mt-sui-16">
+    <h3 className="text-sui-text-default">Additional Info</h3>
+  </div>
+  <TextAreaField label="Bio" />
+  <Button className="mt-sui-24">Submit</Button>
+</form>
+```
+
+---
+
+## Layout Primitives
+
+SortUI does not provide explicit layout components (Stack, Inline, Box). Use **Tailwind Flexbox and Grid utilities** for layout.
+
+### Flexbox Patterns
+
+```tsx
+{/* Vertical stack */}
+<div className="flex flex-col gap-sui-16">…</div>
+
+{/* Horizontal inline */}
+<div className="flex flex-row gap-sui-8 items-center">…</div>
+
+{/* Space between (navbar) */}
+<div className="flex items-center justify-between">…</div>
+
+{/* Centered content */}
+<div className="flex items-center justify-center min-h-screen">…</div>
+```
+
+### Grid Patterns
+
+```tsx
+{/* Responsive cards grid */}
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
+  <Card>Item 1</Card>
+  <Card>Item 2</Card>
+  <Card>Item 3</Card>
+</div>
+
+{/* Form grid */}
+<div className="grid grid-cols-1 md:grid-cols-2 gap-sui-16">
+  <InputField label="First Name" />
+  <InputField label="Last Name" />
+  <InputField label="Email" className="md:col-span-2" />
+</div>
+
+{/* Dashboard grid */}
+<div className="grid grid-cols-12 gap-sui-24">
+  <div className="col-span-12 lg:col-span-8">Main</div>
+  <div className="col-span-12 lg:col-span-4">Sidebar</div>
+</div>
+```
+
+---
+
+## Responsive Patterns
+
+### Breakpoints (Tailwind v3)
+
+SortUI uses the **default Tailwind v3 breakpoints**:
+
+| Breakpoint | Min Width | Usage |
+|------------|-----------|-------|
+| `sm` | 640px | Small tablets |
+| `md` | 768px | Tablets |
+| `lg` | 1024px | Laptops |
+| `xl` | 1280px | Desktops |
+| `2xl` | 1536px | Large desktops |
+
+**Mobile-first approach:**
+```tsx
+<div className="p-sui-16 md:p-sui-24 lg:p-sui-32">Content</div>
+```
+
+### Responsive Spacing
+
+| Pattern | Mobile | Tablet | Desktop |
+|---------|--------|--------|---------|
+| Page container padding | `px-sui-16` | `md:px-sui-24` | `lg:px-sui-32` |
+| Section gap | `gap-sui-32` | `md:gap-sui-48` | `lg:gap-sui-64` |
+| Grid columns | 1 | 2 | 3–4 |
+
+```tsx
+<div className="px-sui-16 md:px-sui-24 lg:px-sui-32 py-sui-32 md:py-sui-48 lg:py-sui-64">
+  <div className="max-w-7xl mx-auto">
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
+      {/* Cards */}
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## Radius & Shadow in Layouts (NO `sui-` prefix)
+
+Always use the correct class names (see `tokens.md` for the full list):
+
+```tsx
+{/* ✅ Card with radius + shadow */}
+<div className="bg-sui-bg-card border border-sui-border-default rounded-lg shadow-card p-sui-24">
+  Content
+</div>
+
+{/* ✅ Pill */}
+<div className="rounded-full bg-sui-badge-blue px-sui-12 py-sui-4">Label</div>
+
+{/* ❌ Wrong */}
+<div className="rounded-sui-lg shadow-sui-card" />
+<div className="rounded-lg shadow-md" />
+```
+
+---
+
+## Styling Approach
+
+**Use Tailwind utilities FIRST:**
+```tsx
+<div className="flex items-center gap-sui-12 p-sui-16 bg-sui-bg-default border border-sui-border-default rounded-lg">
+  Content
+</div>
+```
+
+**Use CSS custom properties for dynamic values:**
+```tsx
+<div style={{
+  color: "var(--text-subtle)",
+  padding: "var(--spacing-16)",
+}}>
+  Content
+</div>
+```
+
+**Override component styles via `className`:**
+```tsx
+<Button className="w-full md:w-auto">
+  Full width on mobile, auto on desktop
+</Button>
+```
+
+### Custom CSS (when needed, token-based only)
+
+```css
+.custom-card {
+  background: var(--bg-card);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-24);
+  box-shadow: var(--shadow-card);
+}
+.custom-card:hover {
+  box-shadow: var(--shadow-modal-sm);
+}
+```
+
+---
+
+## Component Reuse Rule (CRITICAL)
+
+**Reuse existing SortUI components** instead of inlining custom markup. This keeps styling consistent across themes.
+
+```tsx
+// ✅ DO — reuse components
+<Badge color="green" shape="pill">Active</Badge>
+<Avatar src="/u.jpg" fallback="MS" size="md" />
+<ProgressBar value={75} label labelText="Upload" />
+<Button variant="default" size="md">Save</Button>
+
+// ❌ DON'T — inline markup
+<span className="inline-flex bg-green-100 text-green-800 px-sui-8 py-sui-4 rounded-full text-xs">Active</span>
+<img src="/u.jpg" className="w-10 h-10 rounded-full" />
+<div className="h-2 bg-sui-bg-muted rounded-full overflow-hidden">
+  <div style={{ width: "75%" }} className="h-full bg-sui-state-primary" />
+</div>
+```
+
+---
+
+## DO / DON'T
+
+**DO:**
+```tsx
+<div className="gap-sui-16 p-sui-24" />
+<div className="bg-sui-bg-default text-sui-text-default" />
+<div className="p-sui-16 md:p-sui-24 lg:p-sui-32" />
+<div className="flex flex-col gap-sui-16" />
+<div className="rounded-md shadow-card" />
+<Button className="w-full md:w-auto">Submit</Button>
+```
+
+**DON'T:**
+```tsx
+<div className="gap-[16px] p-[24px]" />                    {/* ❌ arbitrary */}
+<div className="bg-[#ffffff] text-[#111115]" />            {/* ❌ hex */}
+<div className="lg:p-sui-32 md:p-sui-24 p-sui-16" />       {/* ❌ desktop-first */}
+<Button style={{ padding: "20px" }}>Submit</Button>         {/* ❌ inline style */}
+<div className="rounded-sui-md shadow-sui-default" />       {/* ❌ wrong prefix */}
+<div className="rounded-md shadow-md shadow-lg" />          {/* ❌ generic shadow */}
+```
+
+---
+
+## Layout Examples
+
+### Dashboard Layout
+```tsx
+<div className="min-h-screen bg-sui-bg-subtle">
+  <header className="bg-sui-bg-default border-b border-sui-border-default px-sui-24 py-sui-16">
+    <div className="max-w-7xl mx-auto flex items-center justify-between">
+      <h1 className="text-sui-text-default font-semibold">Dashboard</h1>
+      <nav className="flex gap-sui-12">
+        <Button variant="ghost">Settings</Button>
+      </nav>
+    </div>
+  </header>
+
+  <main className="max-w-7xl mx-auto px-sui-24 py-sui-32">
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-sui-24">
+      <Card>…</Card>
+      <Card>…</Card>
+      <Card>…</Card>
+    </div>
+  </main>
+</div>
+```
+
+### Form Layout
+```tsx
+<div className="max-w-md mx-auto p-sui-24">
+  <form className="flex flex-col gap-sui-16">
+    <h2 className="text-2xl font-semibold text-sui-text-default mb-sui-8">Sign Up</h2>
+    <InputField label="Name" required />
+    <InputField label="Email" type="email" required />
+    <InputField label="Password" type="password" required />
+    <CheckboxWithText label="I agree to the terms" />
+    <Button type="submit" className="mt-sui-16">Create Account</Button>
+  </form>
+</div>
+```
+
+### Article Layout
+```tsx
+<div className="max-w-4xl mx-auto px-sui-24 py-sui-64">
+  <article className="space-y-sui-32">
+    <header className="space-y-sui-16">
+      <h1 className="text-4xl font-bold text-sui-text-default">Article Title</h1>
+      <p className="text-sui-text-muted">Published on Jan 1, 2026</p>
+    </header>
+    <div className="prose">
+      <p className="text-sui-text-default">Article content…</p>
+    </div>
+    <footer className="border-t border-sui-border-default pt-sui-24">
+      <div className="flex items-center gap-sui-12">
+        <Avatar src="/author.jpg" fallback="JD" size="md" />
+        <div>
+          <p className="font-semibold text-sui-text-default">John Doe</p>
+          <p className="text-sm text-sui-text-subtle">Author</p>
+        </div>
+      </div>
+    </footer>
+  </article>
+</div>
+```
+
+---
+
+## Summary
+
+- **Tailwind v3**, mobile-first, semantic tokens
+- **Spacing with `sui-` prefix**: `gap-sui-16`, `p-sui-24`, `m-sui-8`
+- **Radius & Shadow WITHOUT `sui-` prefix**: `rounded-md`, `shadow-card`
+- **Use Flexbox and Grid utilities** for layout
+- **Reuse SortUI components** (Badge, Avatar, Button, ProgressBar, etc.) instead of inlining markup
+- **Responsive breakpoints**: `sm`, `md`, `lg`, `xl`, `2xl`
+- **Semantic color tokens** over hard-coded hex/rgb
+- **Common spacing**: 16px between form fields, 24px card padding, 32px section gaps

package/guidelines/tokens.md

@@ -0,0 +1,354 @@
+# Design Tokens and CSS Guidelines
+
+Design tokens, CSS custom properties, and theming in SortUI. Uses **Tailwind v3** (`^3.4.1`) — never v4.
+
+## Token Format
+
+Tokens are consumed as **CSS custom properties** (variables) and **Tailwind v3 utility classes**.
+
+```css
+/* CSS custom properties */
+color: var(--text-default);
+background: var(--bg-subtle);
+border-radius: var(--radius-md);
+box-shadow: var(--shadow-card);
+
+/* Tailwind v3 classes (via SortUI preset) */
+<div className="bg-sui-bg-default text-sui-text-default rounded-md shadow-card p-sui-24" />
+```
+
+### `sui-` prefix rules (CRITICAL)
+
+The `sui-` prefix is applied **selectively**. Memorize this table.
+
+| Category | Prefix? | Correct | Wrong |
+|---|---|---|---|
+| Color — text | yes | `text-sui-text-default`, `text-sui-text-muted` | `text-default` |
+| Color — background | yes | `bg-sui-bg-default`, `bg-sui-bg-subtle` | `bg-default` |
+| Color — border | yes | `border-sui-border-default` | `border-default` |
+| Color — icon | yes | `text-sui-icon-default`, `text-sui-icon-destructive` | `text-icon-default` |
+| Spacing | yes | `gap-sui-16`, `p-sui-24`, `mx-sui-32`, `space-y-sui-16` | `gap-16` |
+| Badge background | yes | `bg-sui-badge-blue`, `bg-sui-badge-red` | `bg-badge-blue` |
+| **Radius** | **no** | `rounded-md`, `rounded-lg`, `rounded-full`, `rounded-card-md` | ~~`rounded-sui-md`~~ |
+| **Shadow** | **no** | `shadow-default`, `shadow-card`, `shadow-focus`, `shadow-modal-md` | ~~`shadow-sui-default`~~ ~~`shadow-md`~~ |
+| **Border width** | **no** | `border` (1px), `border-md` (1.5px), `border-lg` (2px) | ~~`border-sui-md`~~ |
+| **Font size** | **no** | `text-sm`, `text-base`, `text-2xl` | ~~`text-sui-md`~~ |
+
+---
+
+## Theming — 4 Themes
+
+SortUI provides **4 theme variants**. All four must render correctly for any generated UI.
+
+- `light` — zinc/blue, light mode (default)
+- `dark` — zinc/blue, dark mode
+- `theme-2` — neutral/orange, light mode
+- `theme-2-dark` — neutral/orange, dark mode
+
+**Apply theme class to `<html>` or `<body>`:**
+```tsx
+<html className="dark">
+  {/* App renders in dark theme */}
+</html>
+```
+
+---
+
+## Color Tokens
+
+### Text Tokens
+
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--text-default` | Primary text | `text-sui-text-default` |
+| `--text-subtle` | Secondary text | `text-sui-text-subtle` |
+| `--text-muted` | Tertiary text | `text-sui-text-muted` |
+| `--text-hint` | Placeholder text | `text-sui-text-hint` |
+| `--text-inverted-default` | Text on dark backgrounds | `text-sui-text-inverted-default` |
+| `--text-inverted-subtle` | Subtle text on dark | `text-sui-text-inverted-subtle` |
+| `--text-destructive` | Error/danger text | `text-sui-text-destructive` |
+| `--text-primary` | Primary brand text | `text-sui-text-primary` |
+| `--text-success` | Success text | `text-sui-text-success` |
+| `--text-warning` | Warning text | `text-sui-text-warning` |
+| `--text-informative` | Info text | `text-sui-text-informative` |
+
+### Background Tokens
+
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--bg-default` | Page/card background | `bg-sui-bg-default` |
+| `--bg-subtle` | Subtle background | `bg-sui-bg-subtle` |
+| `--bg-muted` | Muted background | `bg-sui-bg-muted` |
+| `--bg-card` | Card background | `bg-sui-bg-card` |
+| `--bg-inverted` | Dark background | `bg-sui-bg-inverted` |
+
+**State backgrounds:** `bg-sui-state-primary`, `bg-sui-state-primary-hover`, `bg-sui-state-destructive`, `bg-sui-state-soft`, `bg-sui-state-ghost`, `bg-sui-state-disabled`, etc.
+
+**Badge backgrounds (semantic color scale):**
+- `bg-sui-badge-red`, `bg-sui-badge-orange`, `bg-sui-badge-yellow`, `bg-sui-badge-lime`, `bg-sui-badge-green`, `bg-sui-badge-emerald`, `bg-sui-badge-teal`, `bg-sui-badge-cyan`, `bg-sui-badge-sky`, `bg-sui-badge-blue`, `bg-sui-badge-indigo`, `bg-sui-badge-violet`, `bg-sui-badge-purple`, `bg-sui-badge-fuchsia`, `bg-sui-badge-pink`, `bg-sui-badge-gray`, `bg-sui-badge-white`, `bg-sui-badge-inverted`
+
+### Border Color Tokens
+
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--border-default` | Default borders | `border-sui-border-default` |
+| `--border-darker` | Stronger borders | `border-sui-border-darker` |
+| `--border-strong` | Strong borders | `border-sui-border-strong` |
+| `--border-accent` | Accent borders | `border-sui-border-accent` |
+| `--border-destructive` | Error borders | `border-sui-border-destructive` |
+| `--border-informative` | Info borders | `border-sui-border-informative` |
+| `--border-success` | Success borders | `border-sui-border-success` |
+| `--border-warning` | Warning borders | `border-sui-border-warning` |
+
+### Icon Color Tokens
+
+| Token | Usage | Tailwind class |
+|-------|-------|----------------|
+| `--icon-default` | Primary icons | `text-sui-icon-default` |
+| `--icon-default-subtle` | Subtle icons | `text-sui-icon-subtle` |
+| `--icon-default-muted` | Muted icons | `text-sui-icon-muted` |
+| `--icon-default-disabled` | Disabled icons | `text-sui-icon-disabled` |
+| `--icon-inverted-default` | Icons on dark backgrounds | `text-sui-icon-inverted-default` |
+| `--icon-destructive` | Error icons | `text-sui-icon-destructive` |
+| `--icon-informative` | Info icons | `text-sui-icon-informative` |
+| `--icon-success` | Success icons | `text-sui-icon-success` |
+| `--icon-warning` | Warning icons | `text-sui-icon-warning` |
+
+---
+
+## Typography Tokens
+
+### Font Family
+
+| Token | Tailwind | Default |
+|-------|----------|---------|
+| `--font-body` | `font-sans` | Geist Sans (bundled) |
+| `--font-headline` | `font-headline` | Geist Sans |
+| `--font-quote` | `font-quote` | Redaction (bundled) |
+| `--font-quote-alt` | `font-quote-alt` | Redaction 35 |
+| `--font-code` | `font-code` | Geist Mono (bundled) |
+
+### Font Size (Tailwind v3 classes)
+
+Use `text-xs` through `text-9xl` — these are native Tailwind classes wired to SortUI tokens. **Do NOT use `text-sui-*` font-size classes.**
+
+| Class | Size | Usage |
+|-------|------|-------|
+| `text-xs` | 12px | Small labels, captions |
+| `text-sm` | 14px | Body text (small) |
+| `text-base` | 16px | Body text (default) — also `text-md` |
+| `text-lg` | 18px | Large body text |
+| `text-xl` | 20px | Small headings |
+| `text-2xl` | 24px | Headings (H3) |
+| `text-3xl` | 30px | Headings (H2) |
+| `text-4xl` | 36px | Headings (H1) |
+| `text-5xl` – `text-9xl` | 48–128px | Display / hero text |
+
+### Font Weight
+
+`font-light` (300), `font-normal` (400), `font-medium` (500), `font-semibold` (600), `font-bold` (700), `font-extrabold` (800), `font-black` (900).
+
+---
+
+## Shadow Tokens (NO `sui-` prefix)
+
+Use ONLY these Figma-aligned shadow classes. **Never** use `shadow-sm`, `shadow-md`, `shadow-lg`, arbitrary `shadow-[…]`, or `shadow-sui-*`.
+
+| Tailwind class | CSS var | Usage |
+|----------------|---------|-------|
+| `shadow-default` | `--shadow-default` | Default element shadow |
+| `shadow-card` | `--shadow-card` | Card shadow |
+| `shadow-card-base` | `--shadow-card-base` | Base card shadow |
+| `shadow-focus` | `--shadow-focus` | Focus ring |
+| `shadow-destructive-focus` | `--shadow-destructive-focus` | Destructive focus ring |
+| `shadow-misc-focus` | `--shadow-misc-focus` | Misc focus |
+| `shadow-input-focus` | `--shadow-input-focus` | Input focus |
+| `shadow-modal-sm` | `--shadow-modal-sm` | Small modal |
+| `shadow-modal-md` | `--shadow-modal-md` | Medium modal |
+| `shadow-modal-lg` | `--shadow-modal-lg` | Large modal |
+| `shadow-switch-handle` | `--shadow-switch-handle` | Switch handle |
+| `shadow-checkbox` / `shadow-checkbox-active` | | Checkbox |
+| `shadow-inset-bottom` / `-soft` / `-strong` | | Inset bottom |
+| `shadow-tab-active` | `--shadow-tab-active` | Active tab |
+| `shadow-button-default` / `-press` / `-secondary` / `-secondary-press` | | Button shadows |
+
+```tsx
+<div className="shadow-card" />
+<div className="shadow-default" />
+<button className="shadow-button-default active:shadow-button-press" />
+```
+
+---
+
+## Border & Radius Tokens
+
+### Border Width (NO `sui-` prefix)
+
+| Class | Width |
+|-------|-------|
+| `border-sm` | 0.5px |
+| `border` | 1px (default) |
+| `border-md` | 1.5px |
+| `border-lg` | 2px |
+| `border-xl` | 3px |
+| `border-2xl` | 4px |
+
+### Border Radius (NO `sui-` prefix)
+
+| Class | Radius |
+|-------|--------|
+| `rounded-none` | 0px |
+| `rounded-2xs` | 2px |
+| `rounded-xs` | 4px |
+| `rounded-sm` | 6px |
+| `rounded-md` | 8px |
+| `rounded-lg` | 12px |
+| `rounded-xl` | 16px |
+| `rounded-2xl` | 24px |
+| `rounded-3xl` | 28px |
+| `rounded-full` | 9999px (pill) |
+| `rounded-card-none` / `-xs` / `-sm` / `-md` / `-lg` | Card-specific |
+
+```tsx
+<div className="rounded-md" />      {/* 8px */}
+<div className="rounded-lg" />      {/* 12px */}
+<div className="rounded-full" />    {/* pill */}
+<div className="rounded-card-md" /> {/* card-aligned */}
+```
+
+---
+
+## Spacing Tokens (WITH `sui-` prefix)
+
+Use spacing tokens from `--spacing-1` to `--spacing-384`, exposed as `p-sui-16`, `gap-sui-12`, etc.
+
+| Class | Size | Common usage |
+|-------|------|--------------|
+| `gap-sui-none` | 0 | No spacing |
+| `gap-sui-4` | 4px | Tight groups |
+| `gap-sui-8` | 8px | Small |
+| `gap-sui-12` | 12px | Inline items |
+| `gap-sui-16` | 16px | Form fields |
+| `gap-sui-20` | 20px | Medium+ |
+| `gap-sui-24` | 24px | Card internal |
+| `gap-sui-32` | 32px | Section break |
+| `gap-sui-48` | 48px | Major section |
+| `gap-sui-64` | 64px | Page section |
+
+Works across all spacing utilities: `p-`, `m-`, `gap-`, `space-x-`, `space-y-`, etc.
+
+```tsx
+<div className="gap-sui-16 p-sui-24" />
+<div className="space-y-sui-16" />
+<div className="mx-sui-32 my-sui-24" />
+```
+
+---
+
+## DO / DON'T
+
+**DO:**
+```tsx
+// Semantic color tokens
+<div className="bg-sui-bg-subtle text-sui-text-default border border-sui-border-default" />
+
+// Correct radius (NO sui- prefix)
+<div className="rounded-md" />
+<div className="rounded-lg" />
+
+// Correct shadow (NO sui- prefix)
+<div className="shadow-card" />
+<div className="shadow-default" />
+
+// Correct spacing (WITH sui- prefix)
+<div className="p-sui-24 gap-sui-16" />
+
+// CSS variable for dynamic values
+<div style={{ color: "var(--text-subtle)" }} />
+```
+
+**DON'T:**
+```tsx
+// ❌ sui- prefix on radius/shadow
+<div className="rounded-sui-md shadow-sui-default" />
+
+// ❌ Generic Tailwind shadow primitives
+<div className="shadow-md shadow-lg" />
+
+// ❌ Hardcoded hex/arbitrary values
+<div className="bg-[#fafafa] text-[#111115] gap-[16px]" />
+
+// ❌ Missing sui- on colors/spacing
+<div className="bg-bg-default text-text-default gap-16" />
+```
+
+---
+
+## Token Usage Examples
+
+**Card:**
+```tsx
+<div className="bg-sui-bg-card border border-sui-border-default rounded-card-md shadow-card p-sui-24">
+  <h3 className="text-sui-text-default font-semibold">Card title</h3>
+  <p className="text-sui-text-subtle">Card body</p>
+</div>
+```
+
+**Button (primary):**
+```css
+.custom-button {
+  background: var(--bg-state-primary);
+  color: var(--text-inverted-default);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-12) var(--spacing-24);
+  box-shadow: var(--shadow-button-default);
+}
+.custom-button:hover { background: var(--bg-state-primary-hover); }
+.custom-button:active { box-shadow: var(--shadow-button-press); }
+```
+
+**Input:**
+```css
+.custom-input {
+  background: var(--bg-default);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  color: var(--text-default);
+  padding: var(--spacing-8) var(--spacing-12);
+}
+.custom-input:focus {
+  border-color: var(--border-informative);
+  box-shadow: var(--shadow-input-focus);
+}
+```
+
+---
+
+## Chart Color Tokens
+
+For data visualization (Recharts integration):
+
+| Token | Default |
+|-------|---------|
+| `--chart-1` | blue |
+| `--chart-2` | green |
+| `--chart-3` | orange |
+| `--chart-4` | red |
+| `--chart-5` | purple |
+
+**Usage in charts (note `isAnimationActive={false}` — required for React 19):**
+```tsx
+<Line dataKey="revenue" stroke="var(--chart-1)" isAnimationActive={false} />
+<Bar  dataKey="sales"   fill="var(--chart-2)"   isAnimationActive={false} />
+```
+
+---
+
+## Summary
+
+- **Use semantic tokens** over raw values
+- **Tokens are CSS custom properties** (`var(--token-name)`)
+- **Tailwind v3** utility classes — never emit Tailwind v4 syntax
+- **Selective `sui-` prefix** — colors + spacing yes; radius + shadow + border-width + font-size no
+- **Theming** via class on root element (`light`, `dark`, `theme-2`, `theme-2-dark`)
+- **All tokens** automatically adapt to theme changes