@sarunyu/system-one 2.0.2 → 3.0.1

package/llms.txt

@@ -1,8 +1,6 @@
 # @sarunyu/system-one
 
-React UI component library for AI generation tools (Figma Make, v0, Lovable). You compose pages from layout + UI primitives — both are in the library. Tailwind CSS v4 + CSS custom properties.
-
----
+React component library. Tailwind CSS v4 + CSS custom properties. 13 production-ready components. Built for AI-powered generation tools (v0, Lovable, Figma Make).
 
 ## Install
 
@@ -10,36 +8,35 @@ React UI component library for AI generation tools (Figma Make, v0, Lovable). Yo
 npm install @sarunyu/system-one
 ```
 
-## Setup — REQUIRED FIRST STEP
-
-**You MUST import the stylesheet once at the app root. Without this, components render unstyled and layout will break.**
+## Setup by Platform
 
-Pick the entry file that already exists in the project. In order of preference:
+### v0 / Next.js (App Router)
 
 ```tsx
-// Figma Make / Vite / CRA — top of /App.tsx (or /src/App.tsx)
+// app/layout.tsx
 import "@sarunyu/system-one/styles.css"
+```
 
-// Next.js App Router — top of /app/layout.tsx
-import "@sarunyu/system-one/styles.css"
+Components are pre-annotated with `"use client"`. Safe to import anywhere — Server Components, Client Components, pages.
+
+### Next.js (Pages Router)
 
-// Next.js Pages Router — top of /pages/_app.tsx
+```tsx
+// pages/_app.tsx
 import "@sarunyu/system-one/styles.css"
 ```
 
-Rules:
-- Import the stylesheet **exactly once**, as the first import in the entry file.
-- Do **not** re-import it inside individual components.
-- Do **not** add a Tailwind config — the library ships pre-built CSS.
-- If Figma Make complains about a missing import path, place the line at the very top of `App.tsx`.
+### Figma Make / Lovable / Vite
+
+```tsx
+// src/main.tsx
+import "@sarunyu/system-one/styles.css"
+```
 
-## Import components
+## Import
 
 ```tsx
 import {
-  // Layout
-  Page, PageHeader, Section, Toolbar, Stack, CardGrid,
-  // UI
   Button, Input, TextArea, SearchInput,
   Dropdown, DropdownMultiple, OptionList,
   Tag, StatusTag, Chip,
@@ -52,199 +49,6 @@ import {
 
 ---
 
-## Color rules — read this before touching any className
-
-**Never** use Tailwind's literal color utilities for brand or semantic roles. Only use design token CSS variables.
-
-| Role | ✅ Use this token | ❌ Never this |
-|---|---|---|
-| Brand / CTA | `var(--primary-action)` | `bg-blue-600`, `text-blue-500` |
-| Hover / active | `var(--primary-action-hover)`, `var(--primary-action-active)` | `hover:bg-blue-700` |
-| Body text | `var(--foreground)` | `text-gray-900` |
-| Secondary text | `var(--muted-foreground)` | `text-gray-500` |
-| Page background | `var(--background)` | `bg-white`, `bg-gray-50` |
-| Card surface | `var(--card)` | `bg-white` |
-| Subtle surface | `var(--muted)` | `bg-gray-100` |
-| Border | `var(--border)` | `border-gray-200` |
-| Subtle divider | `var(--divider)` | `border-gray-100` |
-| Success | `var(--success)` | `text-green-600` |
-| Error / danger | `var(--destructive)` | `text-red-500` |
-| Warning | `var(--accent-orange)` | `text-orange-400` |
-
-Usage in className: `className="bg-[var(--card)] text-[var(--foreground)] border-[var(--border)]"`
-Usage in style: `style={{ color: "var(--primary-action)" }}`
-
----
-
-## Layout — design freely, but color with tokens
-
-**Layout is yours to design.** Use any structure, spacing, grid, or visual treatment you want. The two hard rules are:
-
-1. **Colors** — every color must come from a design token (see Color rules above). No `bg-blue-500`, no `text-gray-900`.
-2. **UI components** — if the element matches a library component, use it (see The One Rule below).
-
-Everything else — container widths, grids, flex layouts, padding, hero sections, sidebars, split-pane, masonry, sticky headers, full-bleed backgrounds — is open. Design whatever looks great.
-
-### Layout convenience components (optional)
-
-The library exports these if you want quick, consistent scaffolding. Use them when they fit; skip them and write raw Tailwind when they don't.
-
-| Component | What it gives you |
-|---|---|
-| `<Page width="lg">` | `max-w-[1200px] mx-auto px-6 py-10 flex flex-col gap-12` |
-| `<PageHeader title actions eyebrow>` | Responsive title + description + right-aligned actions |
-| `<Section title description actions>` | Content group with optional header, `flex flex-col gap-6` |
-| `<Toolbar end>` | Left cluster + right cluster split with `ml-auto` |
-| `<Stack direction gap align justify wrap>` | Flex col/row with typed gap scale |
-| `<CardGrid cols>` | Responsive grid, always `gap-6` |
-
-```tsx
-// Using convenience components
-<Page width="lg">
-  <PageHeader title="Events" actions={<Button variant="primary" size="md">Add</Button>} />
-  <Section title="All Events">
-    <CardGrid cols={3}><Card ... /></CardGrid>
-  </Section>
-</Page>
-
-// Or go fully custom — both are fine
-<div className="min-h-screen bg-[var(--background)]">
-  <div className="relative h-[480px] bg-[var(--primary-action)] flex items-end pb-16 px-12">
-    <h1 className="text-5xl font-bold text-[var(--on-primary-action)]">Events</h1>
-  </div>
-  <div className="max-w-[1400px] mx-auto px-8 -mt-12 grid grid-cols-4 gap-6">
-    <Card variant="desktop" ... />
-  </div>
-</div>
-```
-
-**Stack gap scale** (if used): `1`=4px · `2`=8px · `3`=12px · `4`=16px · `6`=24px · `8`=32px · `10`=40px · `12`=48px
-
----
-
-## The One Rule: use library UI components, never recreate them
-
-If a UI element matches a component in the list below → import it. Do not rebuild it with raw HTML + Tailwind. Do not add classes that restyle its internal look (colors, border, padding, radius, focus ring). The component already owns those.
-
-```tsx
-// ✅ CORRECT
-<Input placeholder="Email" value={email} onChange={setEmail} />
-<Button variant="primary" size="md">Sign in</Button>
-<Tag text="Active" variant="green" />
-
-// ❌ WRONG — never recreate library components
-<input className="border rounded-xl px-4 py-3 w-full" placeholder="Email" />
-<button className="bg-blue-600 text-white px-6 py-2 rounded-lg">Sign in</button>
-<span className="bg-green-100 text-green-700 px-2 py-1 rounded">Active</span>
-```
-
-**If the element is NOT in the library → build it freely with Tailwind + tokens.** The library does NOT provide: modal/dialog, sidebar, table, accordion, tooltip, progress bar, avatar, breadcrumb, slider, toggle/switch, file upload, chart, carousel, skeleton, pagination, toast/banner, stepper, menu. Build these with plain HTML + Tailwind + the design tokens above.
-
----
-
-## Starter snippets
-
-These are minimal correct examples. Layout structure is up to you — the important parts are the component imports and the `var(--...)` tokens.
-
-**List page (using convenience components):**
-
-```tsx
-import { Page, PageHeader, Section, Toolbar, CardGrid, Button, SearchInput, TabGroup, Card } from "@sarunyu/system-one"
-
-export default function EventsPage() {
-  return (
-    <div className="min-h-screen bg-[var(--background)] text-[var(--foreground)]">
-      <Page width="lg">
-        <PageHeader
-          title="Events"
-          description="Browse and manage your events."
-          actions={<Button variant="primary" size="md">New Event</Button>}
-        />
-        <Section title="All Events">
-          <Toolbar end={<SearchInput size="sm" placeholder="Search..." value="" onChange={() => {}} />}>
-            <TabGroup items={[{ id: "all", title: "All" }, { id: "mine", title: "Mine" }]} activeId="all" onChange={() => {}} size="md" />
-          </Toolbar>
-          <CardGrid cols={3}>
-            <Card variant="desktop" title="Annual Conference" date="Jun 23, 2024" time="08:30 - 12:00" location="Main Hall" count="150/200" tagStatus="registered" image="/banner.jpg" />
-          </CardGrid>
-        </Section>
-      </Page>
-    </div>
-  )
-}
-```
-
-**List page (custom layout — equally valid):**
-
-```tsx
-import { Button, SearchInput, TabGroup, Card } from "@sarunyu/system-one"
-
-export default function EventsPage() {
-  return (
-    <div className="min-h-screen bg-[var(--background)]">
-      {/* Hero */}
-      <div className="bg-[var(--primary-action)] px-12 pt-20 pb-32">
-        <h1 className="text-5xl font-bold text-[var(--on-primary-action)]">Events</h1>
-        <p className="mt-3 text-lg text-[var(--on-primary-action)] opacity-80">Browse and manage your events.</p>
-      </div>
-      {/* Content pulled up over hero */}
-      <div className="max-w-[1400px] mx-auto px-8 -mt-16">
-        <div className="flex items-center justify-between mb-6">
-          <TabGroup items={[{ id: "all", title: "All" }, { id: "mine", title: "Mine" }]} activeId="all" onChange={() => {}} size="md" />
-          <div className="flex gap-3">
-            <SearchInput size="sm" placeholder="Search..." value="" onChange={() => {}} />
-            <Button variant="primary" size="md">New Event</Button>
-          </div>
-        </div>
-        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-6">
-          <Card variant="desktop" title="Annual Conference" date="Jun 23, 2024" time="08:30 - 12:00" location="Main Hall" count="150/200" tagStatus="registered" image="/banner.jpg" />
-        </div>
-      </div>
-    </div>
-  )
-}
-```
-
-**Form page:**
-
-```tsx
-import { Stack, Input, TextArea, DateInput, TimeInput, Dropdown, Button } from "@sarunyu/system-one"
-
-<div className="max-w-[480px] mx-auto px-6 py-12 space-y-6">
-  <h1 className="text-3xl font-semibold text-[var(--foreground)]">Create Event</h1>
-  <Stack gap={5}>
-    <Input placeholder="Event Name" value={name} onChange={setName} />
-    <TextArea placeholder="Description" value={desc} onChange={setDesc} />
-    <div className="grid grid-cols-2 gap-3">
-      <DateInput placeholder="Start date" mode="single" value={date} onChange={setDate} />
-      <TimeInput placeholder="Start time" value={time} onChange={setTime} />
-    </div>
-    <Dropdown placeholder="Category" options={cats} value={cat} onChange={setCat} />
-    <Button variant="primary" size="md" className="w-full">Create Event</Button>
-  </Stack>
-</div>
-```
-
----
-
-## Typography scale
-
-The library does NOT preset h1–h6 — set them yourself with Tailwind. Always pair with token colors.
-
-- Page title (h1): `text-3xl md:text-4xl font-semibold tracking-tight text-[var(--foreground)]`
-- Section title (h2): `text-2xl font-semibold text-[var(--foreground)]`
-- Subsection (h3): `text-lg font-semibold text-[var(--foreground)]`
-- Body: `text-base text-[var(--foreground)]` — never smaller than `text-sm` for reading content
-- Caption / meta: `text-sm text-[var(--muted-foreground)]`
-
-### Radius
-
-- Inputs, buttons, small elements: `rounded-md` (6px)
-- Cards, panels: `rounded-xl` (12px) or `rounded-2xl` (16px)
-- Pills / avatars: `rounded-full`
-
----
-
 ## Components
 
 ### Button
@@ -258,19 +62,17 @@ Icon-only sizes: `icon-xs` | `icon-sm` | `icon-md` | `icon-lg` | `icon-xl`
 <Button variant="outline" size="md" onClick={fn}>Cancel</Button>
 <Button variant="plain" size="sm">Learn more</Button>
 <Button variant="primary" size="md" leftIcon={<Icon />}>Add item</Button>
+<Button variant="outline" size="md" rightIcon={<Icon />}>Continue</Button>
 <Button size="icon-md" aria-label="Settings"><GearIcon /></Button>
 ```
 
 Props: `variant`, `size`, `leftIcon`, `rightIcon`, `disabled`, `onClick`, `className`, `children`
 
-Rules:
-- One `primary` per context. Supporting actions use `outline` or `plain`.
-- For mobile full-width CTAs use `className="w-full"`. Default hug width fits short labels.
-- Do not add classes that change background, border, padding, or radius.
+---
 
 ### Input
 
-Floating-label text input.
+Floating-label text input with validation states.
 
 ```tsx
 <Input placeholder="Email" value={email} onChange={setEmail} />
@@ -283,10 +85,7 @@ Floating-label text input.
 
 Props: `placeholder`, `value`, `onChange`, `type`, `unit`, `showCount`, `maxCount`, `forceState` (`"default"` | `"focus"` | `"error"` | `"disabled"`), `errorMessage`, `required`, `className`
 
-Rules:
-- Keep `placeholder` short — long text breaks the floating label.
-- Never show helper text and `errorMessage` at the same time.
-- Do not override border or background — use `forceState` instead.
+---
 
 ### TextArea
 
@@ -300,8 +99,12 @@ Multi-line input. API mirrors Input.
 
 Props: `placeholder`, `value`, `onChange`, `showCount`, `maxCount`, `forceState`, `errorMessage`, `required`, `className`
 
+---
+
 ### SearchInput
 
+Search field with icon and clear button.
+
 ```tsx
 <SearchInput placeholder="Search events..." value={q} onChange={setQ} />
 <SearchInput size="sm" placeholder="Filter by name..." />
@@ -309,7 +112,11 @@ Props: `placeholder`, `value`, `onChange`, `showCount`, `maxCount`, `forceState`
 
 Props: `placeholder`, `value`, `onChange`, `size` (`"lg"` | `"sm"`), `className`
 
-### Dropdown / DropdownMultiple
+---
+
+### Dropdown
+
+Single-select dropdown.
 
 ```tsx
 <Dropdown
@@ -322,7 +129,17 @@ Props: `placeholder`, `value`, `onChange`, `size` (`"lg"` | `"sm"`), `className`
   value={selected}
   onChange={setSelected}
 />
+```
 
+Props: `placeholder`, `options` (`Array<{ label: string, value: string, disabled?: boolean }>`), `value`, `onChange`, `disabled`, `className`
+
+---
+
+### DropdownMultiple
+
+Multi-select dropdown with checkboxes.
+
+```tsx
 <DropdownMultiple
   placeholder="Select tags"
   options={options}
@@ -331,32 +148,18 @@ Props: `placeholder`, `value`, `onChange`, `size` (`"lg"` | `"sm"`), `className`
 />
 ```
 
-Props (single): `placeholder`, `options`, `value`, `onChange`, `disabled`, `className`
-Props (multi): `placeholder`, `options`, `values`, `onChange`, `disabled`, `className`
-
-Use `Dropdown` for single-select, `DropdownMultiple` for multi-select.
-
-### OptionList
-
-Scrollable option list for custom popups.
-
-```tsx
-<OptionList
-  options={[{ label: "Item A", value: "a" }, { label: "Item B", value: "b" }]}
-  selectedValue={value}
-  onSelect={setValue}
-/>
+Props: `placeholder`, `options`, `values`, `onChange`, `disabled`, `className`
 
-<OptionList options={options} selectedValues={values} onToggle={toggleValue} />
-```
+---
 
 ### Tag
 
-Compact colored label for categories/filters.
+Compact colored label. Use for categories, statuses, filters.
 
 Variants: `blue` | `green` | `yellow` | `red` | `gray` | `lime`
 Sizes: `large` (default) | `small`
-Semantics: `green` = positive, `red` = error, `yellow` = warning/pending, `blue` = informational, `gray` = neutral
+
+Color semantics: `green` → positive/active, `red` → error/danger, `yellow` → warning/pending, `blue` → informational, `gray` → neutral/inactive
 
 ```tsx
 <Tag text="Active" variant="green" />
@@ -367,11 +170,11 @@ Semantics: `green` = positive, `red` = error, `yellow` = warning/pending, `blue`
 
 Props: `text`, `variant`, `size`, `close`, `onClose`, `className`
 
-Rules: all tags in the same group use the same size. Do not override padding/radius.
+---
 
 ### StatusTag
 
-Workflow state indicator with a colored dot.
+Process-flow state indicator with colored dot.
 
 Types: `stop` | `success` | `hold` | `processing` | `error`
 
@@ -379,36 +182,41 @@ Types: `stop` | `success` | `hold` | `processing` | `error`
 <StatusTag type="success" />
 <StatusTag type="processing" text="In progress" />
 <StatusTag type="hold" />
+<StatusTag type="error" />
 ```
 
 Props: `type`, `text`, `className`
 
-Use `StatusTag` for process state; use `Tag` for categorical labels.
+Use `StatusTag` for workflow states. Use `Tag` for categorical labels.
+
+---
 
 ### Chip
 
-Toggleable filter chip. Always use in groups of 2+.
+Toggleable filter/selection chip. Always use in groups of 2+.
 
 Types: `single` (default) | `multiple`
 Sizes: `large` | `medium` | `small`
 
 ```tsx
-<div className="flex flex-wrap gap-2">
-  <Chip label="All"      selected={f === "all"}      onClick={() => setF("all")} />
-  <Chip label="Active"   selected={f === "active"}   onClick={() => setF("active")} />
-  <Chip label="Archived" selected={f === "archived"} onClick={() => setF("archived")} />
+{/* Single-select group */}
+<div className="flex gap-2">
+  <Chip label="All" selected={filter === "all"} onClick={() => setFilter("all")} />
+  <Chip label="Active" selected={filter === "active"} onClick={() => setFilter("active")} />
+  <Chip label="Archived" selected={filter === "archived"} onClick={() => setFilter("archived")} />
 </div>
 
+{/* Multi-select */}
 <Chip label="Design" type="multiple" selected={tags.includes("design")} onClick={() => toggle("design")} />
 ```
 
 Props: `label`, `selected`, `onClick`, `type`, `size`, `disabled`, `className`
 
-Rules: one size per group. For a single on/off control use a toggle, not a chip.
+---
 
 ### TabGroup
 
-Tabbed navigation. Always use `TabGroup`; never render `Tab` directly.
+Tabbed navigation. Always use `TabGroup`, not bare `Tab`.
 
 Sizes: `lg` | `md` (default) | `sm`
 
@@ -426,13 +234,15 @@ Sizes: `lg` | `md` (default) | `sm`
 />
 ```
 
-Props: `items` (`{ id, title, icon?, notification?, disabled? }[]`), `activeId`, `onChange`, `size`, `className`
+Props: `items` (`Array<{ id: string, title: string, icon?: boolean, notification?: number, disabled?: boolean }>`), `activeId`, `onChange`, `size`, `className`
+
+---
 
 ### Card
 
-Event/content card with image + metadata.
+Responsive event/content card.
 
-Variants: `desktop` (308px) | `tablet` (224px) | `mobile` (163px)
+Variants: `desktop` (308px wide) | `tablet` (224px wide) | `mobile` (163px wide)
 tagStatus: `not-registered` | `registered` | `full`
 
 ```tsx
@@ -450,7 +260,9 @@ tagStatus: `not-registered` | `registered` | `full`
 
 Props: `variant`, `title`, `date`, `time`, `location`, `count`, `tagStatus`, `image`, `className`
 
-Match the variant to the viewport — `desktop` in wide grids, `tablet`/`mobile` in narrow layouts.
+Match variant to viewport: `desktop` on wide layouts, `tablet` / `mobile` on narrow.
+
+---
 
 ### DateInput
 
@@ -467,59 +279,232 @@ Variants: `popover` (default) | `modal`
 
 Props: `placeholder`, `mode`, `value`, `onChange`, `variant`, `disabled`, `className`
 
-Format is `DD MMM YYYY` — do not override.
+---
 
 ### TimeInput
 
 24-hour time picker.
 
+Modes: `single` | `range`
+
 ```tsx
 <TimeInput placeholder="Start time" value={time} onChange={setTime} />
 <TimeInput mode="range" value={timeRange} onChange={setTimeRange} />
 ```
 
-Props: `placeholder`, `mode` (`single` | `range`), `value`, `onChange`, `disabled`, `className`
+Props: `placeholder`, `mode`, `value`, `onChange`, `disabled`, `className`
 
 ---
 
-## Theming
+### OptionList
+
+Scrollable option list for custom dropdowns.
+
+```tsx
+{/* Single-select */}
+<OptionList
+  options={[{ label: "Item A", value: "a" }, { label: "Item B", value: "b" }]}
+  selectedValue={value}
+  onSelect={setValue}
+/>
+
+{/* Multi-select */}
+<OptionList
+  options={options}
+  selectedValues={values}
+  onToggle={toggleValue}
+/>
+```
+
+Props: `options` (`Array<{ label: string, value: string, disabled?: boolean }>`), `selectedValue`, `onSelect`, `selectedValues`, `onToggle`, `className`
+
+---
+
+## Design Tokens
 
 All tokens are CSS custom properties. Override after the stylesheet import:
 
 ```css
 :root {
-  --primary-action: #7c3aed;          /* brand color */
+  --primary-action: #7c3aed;        /* brand color */
   --primary-action-hover: #6d28d9;
   --primary-action-active: #5b21b6;
-  --font-sans: "Inter", sans-serif;   /* default: Noto Sans Thai */
-  --radius: 8px;
+  --font-sans: "Inter", sans-serif; /* override library default (Noto Sans Thai) */
+  --radius: 8px;                    /* border radius base */
 }
 ```
 
-Key tokens: `--primary-action`, `--background`, `--foreground`, `--card`, `--muted`, `--muted-foreground`, `--border`, `--divider`, `--destructive`, `--success`, `--accent-orange`, `--font-sans`, `--radius`.
+Key tokens:
+- `--primary-action` — brand color (primary buttons, links, active states)
+- `--background` / `--foreground` — page surface and text
+- `--border` — default border color
+- `--muted-foreground` — placeholder and secondary text
+- `--destructive` — error/danger red
+- `--success` — success green
+- `--font-sans` — font family (default: Noto Sans Thai)
+- `--radius` — base border radius (default: 4px)
+
+---
 
-### Dark mode
+## Dark Mode
 
-Add `.dark` to `<html>` (or any ancestor). All components adapt automatically.
+Add `.dark` to `<html>` or any ancestor:
 
 ```tsx
+// Next.js
+<html className={isDark ? "dark" : ""}>
+
+// Vite
 document.documentElement.classList.toggle("dark", isDark)
 ```
 
-### TypeScript
+All components adapt automatically.
+
+---
+
+## TypeScript
 
 ```ts
-import type { ButtonVariant, ButtonSize, TagVariant, ChipSize, PageWidth, StackGap } from "@sarunyu/system-one"
+import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/system-one"
 ```
 
 ---
 
-## Checklist before you render
+## Design Guidance
+
+**You design the layout. The library provides the components.** Compose, arrange, and style page structure freely using Tailwind — the library does not dictate layout. Focus instead on using the components below correctly (right variants, right semantics, right props) so the visual language stays consistent with the design system.
+
+### Anchors the library provides
+
+These are all you need to keep a page visually coherent with the system:
+
+- **Typography** — `<h1>`–`<h4>` are pre-styled (size, weight, line-height). Use them as-is; do not add `text-*` or `font-*` classes to override.
+- **Text color** — body text inherits from `--foreground`. Secondary text: `text-muted-foreground`. Don't hard-code hex colors.
+- **Surfaces** — use `bg-background` / `bg-card` / `bg-muted` so dark mode works automatically.
+- **Brand color** — reference via `--primary-action`, or Tailwind `text-primary-action` / `bg-primary-action`.
+- **Spacing** — Tailwind spacing scale (4px units). Pick whatever gaps/paddings look right; the design system has no prescribed rhythm.
+- **Radius** — `rounded-md` (6px), `rounded-lg` (8px), `rounded-xl` (12px), `rounded-full`.
+
+### Component usage — the only hard rules
+
+Use the library's components for these elements. Do **not** recreate them with raw HTML or Tailwind:
+
+- Buttons → `<Button>` (never `<button>` with utility classes)
+- Text inputs / textareas / search → `<Input>`, `<TextArea>`, `<SearchInput>`
+- Single / multi select → `<Dropdown>`, `<DropdownMultiple>`, `<OptionList>`
+- Date / time pickers → `<DateInput>`, `<TimeInput>`
+- Labels / statuses / filters → `<Tag>`, `<StatusTag>`, `<Chip>`
+- Tabs → `<TabGroup>` (never `<Tab>` alone)
+- Event/content cards → `<Card>`
+
+Pick the correct variant / prop for the semantic role (e.g. `StatusTag type="success"` for success, `Button variant="primary"` once per context). The per-component rules below in "Design Rules" are the full reference.
+
+### Layout freedom
+
+Structure the page however you like — any combination of flex, grid, max-width containers, custom spacing, hero compositions, sidebars, split layouts, dashboards, etc. Use aesthetic judgement: generous padding, clear hierarchy, balanced whitespace. The only layout constraint is that content shouldn't sit flush against viewport edges or adjacent blocks without breathing room.
+
+### Optional: layout helper components
+
+The library also ships a small set of layout primitives (`Page`, `PageHeader`, `Section`, `Toolbar`, `CardGrid`, `Stack`) that some users prefer for rapid scaffolding. They are entirely optional — skip them and design your own layout if that produces a better result. If you do use them, they apply sensible defaults (centered container, 48px section gap, responsive card grid). Full API is in the TypeScript types.
+
+---
+
+## Notes
+
+- No provider or wrapper needed — just import the stylesheet and use components
+- The library ships pre-built CSS — no Tailwind config required in the consuming project
+- If the project already uses Tailwind and you see font differences, override `--font-sans` in your CSS
+- CSS custom properties can be referenced in Tailwind classes: `bg-[var(--primary-action)]`
+
+---
+
+## Component Usage Guide
+
+### Button
+
+Buttons are interactive elements that allow users to click or tap to perform actions — such as submitting a form, saving data, navigating to another page, or opening a popup.
+
+Types: `primary` — main CTA, use once per context. `outline` — secondary action, supports primary without affecting main flow. `plain` — no background or border, low-priority actions. `secondary` (outline-black) — same as outline but black, use when blue is not appropriate.
+
+Sizes: `base` recommended for Desktop. `xl` recommended for Mobile.
+
+States: Default, Hover, Press, Disabled.
+
+### Input
+
+Floating Label Input is a single-line or multi-line field with a label that floats inside.
+
+Types: `Input` — single-line, general text/numeric. `TextArea` — multi-line, for comments or addresses. `Dropdown` — predefined list selection, displays as OptionList.
+
+States: Default, Focus, Error, Disabled.
+
+### Tab
+
+Tabs allow users to switch between different content sections within the same page.
+
+Types: Default (text only), Icon (with icon), Notification (with badge).
+
+States: Default, Active (selected), Disabled.
+
+Sizes: `lg` (default), `md`, `sm`. Always use the same size within one tab group.
+
+### Tag
+
+Tags display categories, types, or short metadata. Status Tags communicate process state.
+
+Tag types: Default (text only), Icon (with icon), Remove (dismissible).
+Tag states: Default, Hover/Press, Disabled.
+Tag sizes: Large, Small.
+
+Status Tag variants: `success` — process completed. `processing` — in progress. `hold` — temporarily paused. `stop` — stopped. `error` — failed.
+
+### Chip
+
+Chips are toggleable filter/selection elements. Always use in groups of 2+.
+
+Types: `single` — one selection at a time. `multiple` — multiple selections simultaneously.
+
+States: Default, Active, Disabled (Default), Disabled (Active).
+
+Sizes: `large`, `medium`, `small`.
+
+---
+
+## Design Rules
+
+### Button Rules
+
+- Maximum width is 343px (`max-w-[343px]`). Never remove or override. Do not detach the component.
+- Do not manually recreate or modify padding (`py-[10px] px-[16px]`) or border-radius (`rounded-[8px]`).
+- Use Primary only once per context. Never place two Primary buttons side-by-side. Use Outline/Secondary for supporting actions.
+- Hug width is correct for short labels only. For long labels, use Fill width or set explicit max-w-[343px].
+
+### Input Rules
+
+- Never override input border or background colors manually — use built-in state variants (Default, Focus, Error, Disabled).
+- Do not recreate input styles manually or adjust gap/height outside the component's tokens.
+- Use Dropdown Tags only for multi-select. For single-select, use standard Dropdown.
+- Keep labelText short enough to fit on one line. Long labels break the floating label layout.
+- Do not show Helper Text and Error Message simultaneously. Error state replaces helper text.
+- Use Option List only when there are multiple selectable values.
+- Always follow the system date format (DD MMM YYYY). Do not mix Thai month names with C.E. year or reorder day/month/year.
+
+### Tab Rules
+
+- Do not override padding, gap, border-radius, element order, or colors inside the tab bar.
+- All tabs in one group must use the same size prop. Never mix sizes.
+- Do not add extra gap or margin between tabs — use built-in spacing tokens only.
+
+### Tag Rules
+
+- Do not override height, padding, or layout of Tag or StatusTag.
+- All tags in the same context must use the same size.
+- Do not reorder internal elements (icon, label, badge) inside Tag or StatusTag.
+- Always use the correct StatusTag variant for its semantic meaning. Never override the color.
 
-1. Stylesheet imported in the app root entry file? (see Setup)
-2. Every UI element that matches a library component (Button, Input, Tag, etc.) uses that component — not raw HTML?
-3. All colors use `var(--...)` tokens, not Tailwind literal color utilities (`bg-blue-500`, `text-gray-900`, etc.)?
-4. Only one `Button variant="primary"` per context?
-5. h1 / h2 / h3 use `text-[var(--foreground)]` (or `text-[var(--on-primary-action)]` on dark surfaces)?
+### Chip Rules
 
-If any answer is "no", fix it before shipping.
+- Keep chip labels short and single-purpose. Long labels cause overflow.
+- Do not override padding, gap, radius, height, element order, or colors.
+- All chips in the same group must share the same size and spacing.
+- Use Chip only for groups with 2+ options. For single options, use a toggle or checkbox instead.