@sarunyu/system-one 2.0.0 → 2.0.2

package/llms.txt

@@ -1,6 +1,8 @@
 # @sarunyu/system-one
 
-React UI component library for AI-powered generation tools (v0, Lovable, Figma Make). Provides production-ready interactive components — you design the layouts freely, the library handles the UI primitives. Tailwind CSS v4 + CSS custom properties.
+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.
+
+---
 
 ## Install
 
@@ -8,35 +10,36 @@ React UI component library for AI-powered generation tools (v0, Lovable, Figma M
 npm install @sarunyu/system-one
 ```
 
-## Setup by Platform
-
-### v0 / Next.js (App Router)
-
-```tsx
-// app/layout.tsx
-import "@sarunyu/system-one/styles.css"
-```
+## Setup — REQUIRED FIRST STEP
 
-Components are pre-annotated with `"use client"`. Safe to import anywhere — Server Components, Client Components, pages.
+**You MUST import the stylesheet once at the app root. Without this, components render unstyled and layout will break.**
 
-### Next.js (Pages Router)
+Pick the entry file that already exists in the project. In order of preference:
 
 ```tsx
-// pages/_app.tsx
+// Figma Make / Vite / CRA — top of /App.tsx (or /src/App.tsx)
 import "@sarunyu/system-one/styles.css"
-```
 
-### Figma Make / Lovable / Vite
+// Next.js App Router — top of /app/layout.tsx
+import "@sarunyu/system-one/styles.css"
 
-```tsx
-// src/main.tsx
+// Next.js Pages Router — top of /pages/_app.tsx
 import "@sarunyu/system-one/styles.css"
 ```
 
-## Import
+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`.
+
+## Import components
 
 ```tsx
 import {
+  // Layout
+  Page, PageHeader, Section, Toolbar, Stack, CardGrid,
+  // UI
   Button, Input, TextArea, SearchInput,
   Dropdown, DropdownMultiple, OptionList,
   Tag, StatusTag, Chip,
@@ -49,6 +52,199 @@ 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
@@ -62,17 +258,19 @@ 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 with validation states.
+Floating-label text input.
 
 ```tsx
 <Input placeholder="Email" value={email} onChange={setEmail} />
@@ -85,7 +283,10 @@ Floating-label text input with validation states.
 
 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
 
@@ -99,12 +300,8 @@ 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..." />
@@ -112,11 +309,7 @@ Search field with icon and clear button.
 
 Props: `placeholder`, `value`, `onChange`, `size` (`"lg"` | `"sm"`), `className`
 
----
-
-### Dropdown
-
-Single-select dropdown.
+### Dropdown / DropdownMultiple
 
 ```tsx
 <Dropdown
@@ -129,17 +322,7 @@ Single-select dropdown.
   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}
@@ -148,18 +331,32 @@ Multi-select dropdown with checkboxes.
 />
 ```
 
-Props: `placeholder`, `options`, `values`, `onChange`, `disabled`, `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}
+/>
+
+<OptionList options={options} selectedValues={values} onToggle={toggleValue} />
+```
 
 ### Tag
 
-Compact colored label. Use for categories, statuses, filters.
+Compact colored label for categories/filters.
 
 Variants: `blue` | `green` | `yellow` | `red` | `gray` | `lime`
 Sizes: `large` (default) | `small`
-
-Color semantics: `green` → positive/active, `red` → error/danger, `yellow` → warning/pending, `blue` → informational, `gray` → neutral/inactive
+Semantics: `green` = positive, `red` = error, `yellow` = warning/pending, `blue` = informational, `gray` = neutral
 
 ```tsx
 <Tag text="Active" variant="green" />
@@ -170,11 +367,11 @@ Color semantics: `green` → positive/active, `red` → error/danger, `yellow`
 
 Props: `text`, `variant`, `size`, `close`, `onClose`, `className`
 
----
+Rules: all tags in the same group use the same size. Do not override padding/radius.
 
 ### StatusTag
 
-Process-flow state indicator with colored dot.
+Workflow state indicator with a colored dot.
 
 Types: `stop` | `success` | `hold` | `processing` | `error`
 
@@ -182,41 +379,36 @@ 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 workflow states. Use `Tag` for categorical labels.
-
----
+Use `StatusTag` for process state; use `Tag` for categorical labels.
 
 ### Chip
 
-Toggleable filter/selection chip. Always use in groups of 2+.
+Toggleable filter chip. Always use in groups of 2+.
 
 Types: `single` (default) | `multiple`
 Sizes: `large` | `medium` | `small`
 
 ```tsx
-{/* 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 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")} />
 </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`, not bare `Tab`.
+Tabbed navigation. Always use `TabGroup`; never render `Tab` directly.
 
 Sizes: `lg` | `md` (default) | `sm`
 
@@ -234,15 +426,13 @@ Sizes: `lg` | `md` (default) | `sm`
 />
 ```
 
-Props: `items` (`Array<{ id: string, title: string, icon?: boolean, notification?: number, disabled?: boolean }>`), `activeId`, `onChange`, `size`, `className`
-
----
+Props: `items` (`{ id, title, icon?, notification?, disabled? }[]`), `activeId`, `onChange`, `size`, `className`
 
 ### Card
 
-Responsive event/content card.
+Event/content card with image + metadata.
 
-Variants: `desktop` (308px wide) | `tablet` (224px wide) | `mobile` (163px wide)
+Variants: `desktop` (308px) | `tablet` (224px) | `mobile` (163px)
 tagStatus: `not-registered` | `registered` | `full`
 
 ```tsx
@@ -260,9 +450,7 @@ tagStatus: `not-registered` | `registered` | `full`
 
 Props: `variant`, `title`, `date`, `time`, `location`, `count`, `tagStatus`, `image`, `className`
 
-Match variant to viewport: `desktop` on wide layouts, `tablet` / `mobile` on narrow.
-
----
+Match the variant to the viewport — `desktop` in wide grids, `tablet`/`mobile` in narrow layouts.
 
 ### DateInput
 
@@ -279,293 +467,59 @@ 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`, `value`, `onChange`, `disabled`, `className`
+Props: `placeholder`, `mode` (`single` | `range`), `value`, `onChange`, `disabled`, `className`
 
 ---
 
-### 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
+## Theming
 
 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; /* override library default (Noto Sans Thai) */
-  --radius: 8px;                    /* border radius base */
+  --font-sans: "Inter", sans-serif;   /* default: Noto Sans Thai */
+  --radius: 8px;
 }
 ```
 
-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)
-
----
+Key tokens: `--primary-action`, `--background`, `--foreground`, `--card`, `--muted`, `--muted-foreground`, `--border`, `--divider`, `--destructive`, `--success`, `--accent-orange`, `--font-sans`, `--radius`.
 
-## Dark Mode
+### Dark mode
 
-Add `.dark` to `<html>` or any ancestor:
+Add `.dark` to `<html>` (or any ancestor). All components adapt automatically.
 
 ```tsx
-// Next.js
-<html className={isDark ? "dark" : ""}>
-
-// Vite
 document.documentElement.classList.toggle("dark", isDark)
 ```
 
-All components adapt automatically.
-
----
-
-## TypeScript
+### TypeScript
 
 ```ts
-import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/system-one"
+import type { ButtonVariant, ButtonSize, TagVariant, ChipSize, PageWidth, StackGap } from "@sarunyu/system-one"
 ```
 
 ---
 
-## Design Guidance
-
-**You own the layout. The library only provides UI components.** Design page structure, layout, and composition entirely on your own — use your best aesthetic judgment to create beautiful, polished pages. The library has no opinions about layout. It only asks that you use its components (listed below) when the UI element matches one the library provides.
-
-### CRITICAL — do NOT recreate library components
-
-The library's components have their own built-in styles (colors, borders, backgrounds, padding, radius, focus states, hover states). You MUST import and use them as-is. **Never** build your own version of a component that exists in the library. Never add Tailwind classes to override their internal appearance.
-
-Common mistakes to avoid:
-
-```tsx
-// ✅ CORRECT — use the library's <Input> component (has floating label, built-in border, focus ring, error state)
-import { Input } from "@sarunyu/system-one"
-<Input placeholder="Email" value={email} onChange={setEmail} />
-<Input placeholder="Password" type="password" value={pw} onChange={setPw} />
-
-// ❌ WRONG — never build your own input with raw HTML + Tailwind
-<input className="border rounded-xl px-4 py-3 w-full" placeholder="Email" />
-<input className="border rounded-xl px-4 py-3 w-full" type="password" placeholder="Password" />
-```
-
-```tsx
-// ✅ CORRECT — use the library's <Tag> component (has built-in colors, padding, border-radius)
-import { Tag } from "@sarunyu/system-one"
-<Tag text="Popular" variant="green" />
-<Tag text="Best Value" variant="blue" />
-<Tag text="Error" variant="red" size="small" />
-
-// ❌ WRONG — never style your own span/div to look like a tag
-<span className="text-green-500 bg-green-500/10 px-2 py-1 rounded">Popular</span>
-<span className="text-blue-500 border border-blue-500 px-2 py-1 rounded">Best Value</span>
-```
-
-```tsx
-// ✅ CORRECT — use the library's <Button> component
-import { Button } from "@sarunyu/system-one"
-<Button variant="primary" size="md">Sign In</Button>
-<Button variant="outline" size="md">Cancel</Button>
-
-// ❌ WRONG — never create buttons with raw HTML + Tailwind
-<button className="bg-blue-600 text-white px-6 py-2 rounded-lg">Sign In</button>
-```
-
-This rule applies to ALL components listed in this document. The components handle their own styling — you only pass props.
-
-### Layout — full creative freedom
-
-Design the layout yourself. Use any technique that produces the best result:
-
-- Flex, grid, CSS columns, absolute positioning, sticky headers, split panes, sidebars, hero sections, masonry grids, full-bleed backgrounds, overlapping elements — anything goes.
-- Choose spacing, padding, max-widths, breakpoints, and visual hierarchy based on what looks best for the specific page. There is no prescribed spacing rhythm or container width.
-- Prioritize aesthetics: generous whitespace, clear visual hierarchy, balanced proportions, elegant transitions and micro-interactions.
-- Do **not** use the library's layout helper components (`Page`, `PageHeader`, `Section`, `Toolbar`, `CardGrid`, `Stack`). They exist for internal use only. Build your own layouts — they will look better.
-
-### Component usage — use ours when we have it, build your own when we don't
-
-The library provides a specific set of UI components. The rule is simple:
-
-**If the UI element matches a component below → import it from `@sarunyu/system-one` and use it.** Do not recreate it with raw HTML or Tailwind. Do not add Tailwind classes to restyle it. The component already has all the styling it needs.
-
-- Buttons → `<Button>` — has built-in variant colors, hover/press states, sizes, icon slots
-- Text inputs → `<Input>` — has built-in floating label, border, focus ring, error state
-- Textareas → `<TextArea>` — has built-in floating label, border, focus ring, error state
-- Search fields → `<SearchInput>` — has built-in search icon, clear button
-- Single select → `<Dropdown>` — has built-in dropdown panel, selection state
-- Multi select → `<DropdownMultiple>` — has built-in checkboxes, multi-selection
-- Option list → `<OptionList>` — has built-in selection highlighting
-- Date picker → `<DateInput>` — has built-in calendar popup
-- Time picker → `<TimeInput>` — has built-in time selection
-- Labels / badges → `<Tag>` — has built-in color variants (blue, green, yellow, red, gray, lime)
-- Status indicators → `<StatusTag>` — has built-in colored dot and status colors
-- Filter chips → `<Chip>` — has built-in toggle state, active styling
-- Tab navigation → `<TabGroup>` — has built-in active tab indicator, sizing
-- Event/content cards → `<Card>` — has built-in image, metadata layout
-
-**If the UI element does NOT match any component above → build it yourself.** Use Tailwind, custom components, or any other approach. Examples of things the library does NOT provide (build these yourself): modals/dialogs, sidebars/navigation, tables, accordions, tooltips, progress bars, avatars, breadcrumbs, sliders, toggles/switches, file uploads, charts, carousels, skeletons/loaders, pagination, alert/notification banners, steppers, menus, etc.
-
-Pick the correct variant / prop for the semantic role (e.g. `StatusTag type="success"` for success, `Button variant="primary"` once per context). See "Design Rules" below for per-component constraints.
-
-### Visual anchors from the library
-
-The library is intentionally unopinionated about page chrome. It sets one global rule only:
-
-- `body { font-family: var(--font-sans) }` — the Noto Sans Thai default, so all text inherits a consistent family.
-
-Everything else — page background, text color, heading sizes, `html` font-size, button/input element defaults — is **yours to own**. The library does not pre-style `<h1>`–`<h6>`; choose the sizes/weights that fit your design.
-
-Use these tokens so custom-built elements stay visually coherent with the design system. Prefer them over hard-coded Tailwind colors for any brand or semantic role:
-
-- **Brand / CTA** — `--primary-action` (hover: `--primary-action-hover`, active: `--primary-action-active`). Use for primary buttons, links, active states, key iconography.
-- **Text** — body: `--foreground`. Secondary/muted: `--muted-foreground`.
-- **Surfaces** — `--background` (page), `--card` (card surface), `--muted` (subtle surface).
-- **Semantic** — `--success` (green), `--destructive` (red), `--accent-orange` (warning/accent).
-- **Border / divider** — `--border` default, `--divider` for subtle separators.
-- **Radius** — `--radius` (default 4px), plus Tailwind `rounded-md` (6px) / `rounded-lg` (8px) / `rounded-xl` (12px) / `rounded-full`.
-
-Consume tokens via inline style (`style={{ color: "var(--primary-action)" }}`) or arbitrary Tailwind (`className="text-[var(--primary-action)] bg-[var(--card)]"`). Do **not** use `bg-blue-500`, `text-orange-400`, `border-gray-200`, etc. for brand or semantic colors.
-
----
-
-## 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.
+## Checklist before you render
 
-### Chip Rules
+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)?
 
-- 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.
+If any answer is "no", fix it before shipping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarunyu/system-one",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "description": "A production-ready React design system built for AI-powered web generation tools (Figma Make, Lovable, V0). Tailwind CSS v4 + CSS custom properties for full theming support.",
   "keywords": [