@sarunyu/system-one 1.3.0 → 1.3.2

package/llms.txt

@@ -1,6 +1,6 @@
 # @sarunyu/system-one
 
-React component library. Tailwind CSS v4 + CSS custom properties. 13 production-ready components. Built for AI-powered generation tools (v0, Lovable, Figma Make).
+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.
 
 ## Install
 
@@ -372,40 +372,93 @@ import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/s
 
 ## 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.
+**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.
 
-### Anchors the library provides
+### CRITICAL — do NOT recreate library components
 
-These are all you need to keep a page visually coherent with the system:
+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.
 
-- **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`.
+Common mistakes to avoid:
 
-### Component usage — the only hard rules
+```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} />
 
-Use the library's components for these elements. Do **not** recreate them with raw HTML or Tailwind:
+// ❌ 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" />
+```
 
-- 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>`
+```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" />
 
-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.
+// ❌ 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>
+```
 
-### Layout freedom
+This rule applies to ALL components listed in this document. The components handle their own styling — you only pass props.
 
-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.
+### Layout — full creative freedom
 
-### Optional: layout helper components
+Design the layout yourself. Use any technique that produces the best result:
 
-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.
+- 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
+
+Use these tokens so custom-built elements stay visually coherent with the design system:
+
+- **Typography** — `<h1>`–`<h4>` are pre-styled. Use them as-is.
+- **Text color** — body text: `--foreground`. Secondary: `text-muted-foreground`. Don't hard-code hex colors.
+- **Surfaces** — `bg-background` / `bg-card` / `bg-muted` (dark mode compatible).
+- **Brand color** — `--primary-action`, or Tailwind `text-primary-action` / `bg-primary-action`.
+- **Radius** — `rounded-md` (6px), `rounded-lg` (8px), `rounded-xl` (12px), `rounded-full`.
+- **Border** — `border-border` for default borders.
 
 ---
 

package/package.json

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