@sarunyu/system-one 2.0.1 → 3.0.0

package/llms.txt

@@ -1,8 +1,6 @@
 # @sarunyu/system-one
 
-React UI component library for AI generation tools (Figma Make, v0, Lovable). You compose layouts; the library supplies styled primitives. 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,30 +8,32 @@ 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 {
@@ -49,129 +49,6 @@ import {
 
 ---
 
-## Layout Anchors — read before composing any page
-
-The library is unopinionated about page chrome, but AI tools produce ugly layouts without anchors. Use these defaults unless the user explicitly asks for something else:
-
-### Container
-
-- Page wrapper: `max-w-[1200px] mx-auto px-6` (desktop). On mobile (`<640px`) reduce to `px-4`.
-- Form wrapper: `max-w-[480px] mx-auto`.
-- Centered auth/onboarding card: `max-w-[400px] mx-auto`.
-- Never let content stretch edge-to-edge on desktop.
-
-### Vertical rhythm
-
-- Page top padding: `py-10` to `py-16`.
-- Between major sections: `space-y-12` or `mt-12`.
-- Between related blocks inside a section: `space-y-6`.
-- Between form fields: `space-y-4` (tight) or `space-y-5` (comfortable).
-- Card grid gap: `gap-6`.
-
-### Typography scale (library does NOT preset h1–h6 — set them yourself)
-
-Use Tailwind utilities with these target sizes. Pair with `--foreground` for body, `--muted-foreground` for secondary text.
-
-- Page title (h1): `text-3xl md:text-4xl font-semibold tracking-tight`
-- Section title (h2): `text-2xl font-semibold`
-- Subsection (h3): `text-lg font-semibold`
-- Body: `text-base` (default) — never smaller than `text-sm` for reading content
-- Caption / meta: `text-sm text-[var(--muted-foreground)]`
-
-### Color rules (prevent theme drift)
-
-Use design tokens for anything brand/semantic. **Never** use Tailwind's literal color utilities (`bg-blue-500`, `text-orange-400`, `border-gray-200`) for these roles.
-
-- Brand / CTA → `var(--primary-action)` (hover `--primary-action-hover`, active `--primary-action-active`)
-- Body text → `var(--foreground)` · muted → `var(--muted-foreground)`
-- Page surface → `var(--background)` · card surface → `var(--card)` · subtle → `var(--muted)`
-- Success → `var(--success)` · error/danger → `var(--destructive)` · warning → `var(--accent-orange)`
-- Border → `var(--border)` · subtle divider → `var(--divider)`
-
-Usage: `className="bg-[var(--card)] text-[var(--foreground)] border-[var(--border)]"` or `style={{ color: "var(--primary-action)" }}`.
-
-### Radius
-
-- Inputs, buttons, small elements: `rounded-md` (6px)
-- Cards, panels: `rounded-xl` (12px) or `rounded-2xl` (16px)
-- Pills / avatars: `rounded-full`
-
----
-
-## Starter Page Template — copy, then adapt
-
-This scaffold produces a well-proportioned page every time. Replace contents but keep the container/spacing shape.
-
-```tsx
-import { Button, Input, Tag, TabGroup } from "@sarunyu/system-one"
-
-export default function Page() {
-  return (
-    <main className="min-h-screen bg-[var(--background)] text-[var(--foreground)]">
-      {/* Top bar — optional */}
-      <header className="border-b border-[var(--border)]">
-        <div className="max-w-[1200px] mx-auto px-6 h-16 flex items-center justify-between">
-          <span className="text-lg font-semibold">Brand</span>
-          <Button variant="primary" size="md">Sign in</Button>
-        </div>
-      </header>
-
-      {/* Page body */}
-      <div className="max-w-[1200px] mx-auto px-6 py-12 space-y-12">
-        {/* Page header */}
-        <section className="space-y-3">
-          <h1 className="text-3xl md:text-4xl font-semibold tracking-tight">
-            Page title
-          </h1>
-          <p className="text-base text-[var(--muted-foreground)] max-w-[640px]">
-            One-line supporting description that sets context for the page.
-          </p>
-        </section>
-
-        {/* Filters */}
-        <section className="flex flex-wrap items-center gap-3">
-          <TabGroup
-            items={[{ id: "all", title: "All" }, { id: "mine", title: "Mine" }]}
-            activeId="all"
-            onChange={() => {}}
-            size="md"
-          />
-        </section>
-
-        {/* Card grid */}
-        <section className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-          {/* use <Card /> here */}
-        </section>
-      </div>
-    </main>
-  )
-}
-```
-
-Form page variant: swap the grid for `<div className="max-w-[480px] mx-auto space-y-5">` and stack `<Input />` fields followed by a single full-width primary `<Button />`.
-
----
-
-## The One Rule: use library 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 build your own
-<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="text-green-500 bg-green-500/10 px-2 py-1 rounded">Active</span>
-```
-
-**If the element is NOT in the list → build it yourself** with Tailwind and 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.
-
----
-
 ## Components
 
 ### Button
@@ -185,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} />
@@ -210,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
 
@@ -227,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..." />
@@ -236,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
@@ -249,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}
@@ -258,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`
+Props: `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 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" />
@@ -294,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`
 
@@ -306,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`
 
@@ -353,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
@@ -377,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
 
@@ -394,46 +279,90 @@ 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`
+
+---
+
+### 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`
 
 ---
 
-## Theming
+## 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 } from "@sarunyu/system-one"
@@ -441,14 +370,141 @@ import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/s
 
 ---
 
-## 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 uses that component, not raw HTML + Tailwind?
-3. Page wrapped in `max-w-[1200px] mx-auto px-6` (or form variant)?
-4. Section rhythm uses `space-y-12` / `space-y-6` / `space-y-4`?
-5. h1 / h2 / h3 sized from the typography scale above?
-6. All brand + semantic colors use `var(--...)` tokens, not `bg-blue-500` etc.?
-7. Only one `Button variant="primary"` per context?
+### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarunyu/system-one",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "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": [