@sarunyu/system-one 1.2.0 → 1.3.1

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
 
@@ -37,9 +37,6 @@ import "@sarunyu/system-one/styles.css"
 
 ```tsx
 import {
-  // Layout primitives (always use these for page structure)
-  Page, PageHeader, Section, Toolbar, CardGrid, Stack,
-  // Components
   Button, Input, TextArea, SearchInput,
   Dropdown, DropdownMultiple, OptionList,
   Tag, StatusTag, Chip,
@@ -373,169 +370,47 @@ import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/s
 
 ---
 
-## Page Layout Patterns
+## Design Guidance
 
-**REQUIRED: every page must be built from the layout primitives below (`Page`, `PageHeader`, `Section`, `Toolbar`, `CardGrid`, `Stack`).** Do not hand-roll page containers with raw `<main>` / `<div>` / Tailwind utilities. These primitives bake in the correct max-width, padding, section spacing, and typographic rhythm — if you skip them, the result will look broken (edge-to-edge content, no section gap, misaligned toolbars).
+**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.
 
-### Layout primitives — API
+### Layout — full creative freedom
 
-**`<Page>`** — top-level page container. Handles max-width, horizontal padding, vertical padding, and the gap between sections.
+Design the layout yourself. Use any technique that produces the best result:
 
-```tsx
-<Page>                  {/* default width="lg" = 1200px */}
-<Page width="sm">       {/* 640px — forms, auth, content */}
-<Page width="md">       {/* 960px — articles */}
-<Page width="lg">       {/* 1200px — default app pages */}
-<Page width="xl">       {/* 1440px — dashboards */}
-<Page width="full">     {/* no max-width */}
-```
-
-**`<PageHeader>`** — the top block of a page: title, description, and optional right-side action buttons.
-
-```tsx
-<PageHeader
-  title="Events"
-  description="Browse and register for upcoming events."
-  actions={<Button variant="primary" size="md">New event</Button>}
-  eyebrow={<Tag text="Live" variant="green" size="small" />}
-/>
-```
-
-Props: `title` (required), `description`, `actions`, `eyebrow`.
-
-**`<Section>`** — a content block with an optional heading row. Stacks heading + body with the correct gap.
+- 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.
 
-```tsx
-<Section title="Upcoming" description="Events in the next 30 days.">
-  {/* body content */}
-</Section>
+### Component usage — use ours when we have it, build your own when we don't
 
-<Section title="Filters" actions={<Button variant="plain" size="sm">Reset</Button>}>
-  <Toolbar>…</Toolbar>
-</Section>
-```
+The library provides a specific set of UI components. The rule is simple:
 
-Props: `title`, `description`, `actions`. All optional — omit all for an unlabelled content block.
+**If the UI element matches a component below → use the library's component.** Do not recreate it with raw HTML or Tailwind.
 
-**`<Toolbar>`** — horizontal wrap-friendly row for search, filters, chips. Auto `flex-wrap` so it stays usable on narrow widths.
+- Buttons → `<Button>`
+- 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>`
+- Event/content cards → `<Card>`
 
-```tsx
-<Toolbar end={<Button variant="outline" size="md">Export</Button>}>
-  <SearchInput placeholder="Search…" value={q} onChange={setQ} className="max-w-[320px]" />
-  <Chip label="All" selected={f === "all"} onClick={() => setF("all")} />
-  <Chip label="Active" selected={f === "active"} onClick={() => setF("active")} />
-</Toolbar>
-```
+**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, badges (use `<Tag>` only if it semantically fits), alert/notification banners, steppers, menus, etc.
 
-The `end` prop pushes content to the right with `ml-auto`.
+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.
 
-**`<CardGrid>`** — responsive grid for cards. Handles breakpoints + gap.
+### Visual anchors from the library
 
-```tsx
-<CardGrid cols={3}>          {/* 1 → 2 → 3 columns */}
-<CardGrid cols={2}>          {/* 1 → 2 columns */}
-<CardGrid cols={4}>          {/* 1 → 2 → 3 → 4 columns */}
-```
-
-**`<Stack>`** — generic vertical/horizontal flex container. Use when you need a gap between arbitrary elements inside a `Section` body.
-
-```tsx
-<Stack gap={4}>                             {/* vertical, 16px gap */}
-<Stack direction="row" gap={3} wrap>        {/* horizontal, 12px gap, wraps */}
-<Stack gap={6} align="center" justify="between">
-```
-
-Props: `direction` (`"col"` default | `"row"`), `gap` (1, 2, 3, 4, 6, 8, 10, 12 — default 4), `align`, `justify`, `wrap`.
-
-### The required page skeleton
-
-Every generated page must follow this shape. Replace content — keep the structure.
-
-```tsx
-import { Page, PageHeader, Section, Toolbar, CardGrid, Button, SearchInput, Chip, Card } from "@sarunyu/system-one";
-
-export default function EventsPage() {
-  return (
-    <Page>
-      <PageHeader
-        title="Events"
-        description="Browse and register for upcoming events."
-        actions={<Button variant="primary" size="md">New event</Button>}
-      />
-
-      <Toolbar>
-        <SearchInput placeholder="Search events…" value={q} onChange={setQ} className="max-w-[320px]" />
-        <Chip label="All" selected={filter === "all"} onClick={() => setFilter("all")} />
-        <Chip label="This week" selected={filter === "week"} onClick={() => setFilter("week")} />
-      </Toolbar>
-
-      <Section title="Upcoming">
-        <CardGrid cols={3}>
-          {events.map((e) => <Card key={e.id} variant="desktop" {...e} />)}
-        </CardGrid>
-      </Section>
-    </Page>
-  );
-}
-```
-
-### Forms — use `<Stack>` inside `<Section>`
-
-```tsx
-<Page width="sm">
-  <PageHeader title="Sign in" description="Welcome back." />
-  <Section>
-    <Stack gap={4} className="max-w-[480px]">
-      <Input placeholder="Email" value={email} onChange={setEmail} />
-      <Input placeholder="Password" type="password" value={pw} onChange={setPw} />
-      <Stack direction="row" gap={3}>
-        <Button variant="primary" size="md">Sign in</Button>
-        <Button variant="outline" size="md">Cancel</Button>
-      </Stack>
-    </Stack>
-  </Section>
-</Page>
-```
-
-### Hero section — use `<PageHeader>` + actions
-
-Do not build a custom hero. Use `PageHeader` with `eyebrow` and `actions` — it already handles title size, description max-width, and action alignment.
-
-```tsx
-<Page>
-  <PageHeader
-    eyebrow={<><Tag text="LIVE" variant="green" size="small" /><Tag text="SET +0.82%" variant="lime" size="small" /></>}
-    title="ลงทุนหุ้นอย่างชาญฉลาด ด้วยข้อมูลเรียลไทม์"
-    description="ติดตามราคา วิเคราะห์เทคนิคอล รับสัญญาณซื้อขาย บนแพลตฟอร์มเดียว"
-    actions={<><Button variant="primary" size="lg">เริ่มต้นใช้งานฟรี</Button><Button variant="outline" size="lg">ดูแผนพรีเมียม</Button></>}
-  />
-  {/* rest of page */}
-</Page>
-```
+Use these tokens to keep custom elements visually coherent with the design system:
 
-### Layout rules (do / don't)
-
-- **Do** always wrap a page in `<Page>`. Never return a naked `<div>` or `<main>` at the top level.
-- **Do** use `<PageHeader>` for the page title — never hand-roll `<h1>` + description + buttons.
-- **Do** use `<Section>` for each content block. Stack multiple `<Section>` children directly inside `<Page>` — the gap is automatic.
-- **Do** use `<Toolbar>` for search/filter rows and `<CardGrid>` for card collections.
-- **Don't** add manual spacing like `mt-8` / `mb-12` between sections — `<Page>` already provides section gap.
-- **Don't** wrap `<Section>` in another flex container — it breaks the rhythm.
-- **Don't** override heading sizes with utility classes — `h1`–`h4` inside these primitives are already sized.
-- **Don't** use `max-w-*` on `<Page>` via className — use the `width` prop instead.
-
-### Spacing scale (used internally by primitives — reference only)
-
-| Purpose | Value |
-|---|---|
-| Between label and input | gap-1 / gap-2 (4–8px) |
-| Between fields in a form | gap-4 (16px) — default `<Stack>` |
-| Between heading and content | gap-6 (24px) — built into `<Section>` |
-| Between top-level sections | gap-12 (48px) — built into `<Page>` |
-| Page horizontal padding | px-6 md:px-8 — built into `<Page>` |
-| Page vertical padding | py-10 — built into `<Page>` |
-
-If you need a custom gap, use `<Stack gap={N}>` with a value from: 1, 2, 3, 4, 6, 8, 10, 12.
+- **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.2.0",
+  "version": "1.3.1",
   "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": [