@sarunyu/system-one 3.0.3 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/AGENTS.md +102 -0
  2. package/README.md +75 -39
  3. package/dist/index.cjs +1103 -252
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.js +1105 -254
  6. package/dist/index.js.map +1 -1
  7. package/dist/src/components/card.d.ts +34 -11
  8. package/dist/src/components/card.d.ts.map +1 -1
  9. package/dist/src/components/checkbox.d.ts +28 -0
  10. package/dist/src/components/checkbox.d.ts.map +1 -0
  11. package/dist/src/components/radio.d.ts +27 -0
  12. package/dist/src/components/radio.d.ts.map +1 -0
  13. package/dist/src/components/table.d.ts +50 -0
  14. package/dist/src/components/table.d.ts.map +1 -0
  15. package/dist/src/index.d.ts +7 -3
  16. package/dist/src/index.d.ts.map +1 -1
  17. package/dist/style.css +1 -1
  18. package/llms.txt +565 -269
  19. package/package.json +4 -2
  20. package/dist/src/components/layout.d.ts +0 -50
  21. package/dist/src/components/layout.d.ts.map +0 -1
package/AGENTS.md ADDED
@@ -0,0 +1,102 @@
1
+ # AGENTS.md — @sarunyu/system-one
2
+
3
+ Instructions for AI coding agents (Claude, Cursor, Copilot, v0, Lovable, Figma Make)
4
+ working in a project that depends on this library.
5
+
6
+ **For the full component catalog, token table, and page recipes, read `llms.txt`
7
+ in this package.** This file is the short version: the rules you must follow.
8
+
9
+ ## Hard rules
10
+
11
+ 1. **Use the library's components for every element it covers.** Never emit:
12
+ - `<button>` with utility classes → use `<Button>`.
13
+ - `<input>` / `<textarea>` → use `<Input>` / `<TextArea>` / `<SearchInput>`.
14
+ - Custom dropdowns, selects, comboboxes → use `<Dropdown>` / `<DropdownMultiple>`.
15
+ - Custom status pills, category labels → use `<Tag>` / `<StatusTag>` / `<Chip>`.
16
+ - Custom tabs → use `<TabGroup>`.
17
+ - Custom checkbox/radio → use `<Checkbox>` / `<Radio>`.
18
+ - Custom date/time pickers → use `<DateInput>` / `<TimeInput>`.
19
+ - Custom tables → use `<Table>` + `<TableRow>` + `<TableHeaderCell>` + `<TableCell>`.
20
+
21
+ 2. **Use token-backed Tailwind classes for color.** Never emit hard-coded colors:
22
+ - Hex (`#3b82f6`), arbitrary (`bg-[#...]`), and palette utilities
23
+ (`bg-blue-600`, `text-gray-500`, `border-slate-200`) are all forbidden.
24
+ - Use `text-foreground`, `text-muted-foreground`, `text-primary-action`,
25
+ `bg-background`, `bg-card`, `bg-muted`, `bg-primary-action`,
26
+ `border-border`, `border-divider`, etc. See `llms.txt` for the full table.
27
+
28
+ 3. **Do not add text/font utility classes to `<h1>`–`<h4>`.** They are pre-styled.
29
+ Use them as-is.
30
+
31
+ 4. **Layout is your job, with plain Tailwind.** The library has NO layout primitives.
32
+ Do not import `Page`, `Section`, `Stack`, `CardGrid`, `Toolbar` — they do not exist.
33
+ Build structure with `<div>` + `flex` / `grid` / `max-w-*` / `gap-*` / `p-*`.
34
+
35
+ 5. **Component props are documented in `llms.txt` and in the `.d.ts` files.**
36
+ - `Input.onChange` receives `(value: string)`, not an event.
37
+ - `placeholder` IS the label (floats up on fill). Don't add a separate `<label>`.
38
+ - Checkbox/Radio take their `label` as a prop. Don't wrap them in `<label>`.
39
+ - All tabs in one `TabGroup` must share the same `size`.
40
+ - One `<Button variant="primary">` per context.
41
+
42
+ ## Setup check
43
+
44
+ Required one-liner in the app entry (App Router: `app/layout.tsx`,
45
+ Pages: `pages/_app.tsx`, Vite: `src/main.tsx`):
46
+
47
+ ```tsx
48
+ import "@sarunyu/system-one/styles.css";
49
+ ```
50
+
51
+ If the screen looks unstyled, this import is missing.
52
+
53
+ ## Dark mode
54
+
55
+ Add `.dark` to any ancestor (usually `<html>`). All tokens adapt automatically.
56
+
57
+ ## Theming
58
+
59
+ Override CSS custom properties after the stylesheet import.
60
+ **Both `:root` (light) and `.dark` (dark) must be overridden separately** —
61
+ the library hard-codes dark-mode colors in its `.dark` block, so a `:root`-only
62
+ override leaves dark mode unchanged.
63
+
64
+ ```css
65
+ :root {
66
+ --primary-action: #7c3aed;
67
+ --primary-action-hover: #6d28d9;
68
+ --primary-action-active: #5b21b6;
69
+ --font-sans: "Inter", sans-serif;
70
+ }
71
+
72
+ .dark {
73
+ --primary-action: #a78bfa;
74
+ --primary-action-hover: #c4b5fd;
75
+ --primary-action-active: #8b5cf6;
76
+ --primary-action-light: color-mix(in srgb, #a78bfa 10%, transparent);
77
+ --primary-action-muted: color-mix(in srgb, #a78bfa 15%, transparent);
78
+ }
79
+ ```
80
+
81
+ Do not override `--radius` — it is a legacy var and has no effect on Tailwind
82
+ utilities. Use `rounded-*` utility classes instead.
83
+
84
+ ## When you need a component the library doesn't provide
85
+
86
+ Build it with tokens. Never introduce new colors.
87
+
88
+ ```tsx
89
+ // Custom badge — uses library tokens
90
+ <span className="inline-flex items-center gap-1 rounded-full bg-primary-action-light text-primary-action px-2 py-0.5 text-xs">
91
+ {text}
92
+ </span>
93
+ ```
94
+
95
+ If the custom thing is conceptually a button/input/tag/chip/tab/card/table,
96
+ **stop and use the library's component instead.** Only build custom when the
97
+ concept isn't covered (hero section, chart, breadcrumb, etc.).
98
+
99
+ ## Read this before generating code
100
+
101
+ - `llms.txt` (this package) — full component catalog + token reference + page recipes.
102
+ - `.d.ts` files in `dist/src/` — exact prop types.
package/README.md CHANGED
@@ -1,7 +1,10 @@
1
1
  # @sarunyu/system-one
2
2
 
3
3
  A production-ready React design system built with **Tailwind CSS v4** and CSS custom properties.
4
- Designed for AI-powered web generation tools — **Figma Make**, **Lovable**, and **V0**.
4
+ Designed for AI-powered UI generation — **Figma Make**, **Lovable**, **v0**, **Cursor**.
5
+
6
+ > **Using this library from an AI tool?** Read [`llms.txt`](./llms.txt) and
7
+ > [`AGENTS.md`](./AGENTS.md). They are the contract for correct use.
5
8
 
6
9
  ## Install
7
10
 
@@ -9,90 +12,123 @@ Designed for AI-powered web generation tools — **Figma Make**, **Lovable**, an
9
12
  npm install @sarunyu/system-one
10
13
  ```
11
14
 
12
- **Peer dependencies:** React ≥ 18
15
+ Peer dep: `react >= 18`.
13
16
 
14
17
  ## Setup
15
18
 
16
- Import the stylesheet once in your app root:
19
+ One import in your app entry:
17
20
 
18
21
  ```tsx
19
- // Next.js: app/layout.tsx or pages/_app.tsx
20
- // Vite: src/main.tsx
22
+ // Next.js App Router: app/layout.tsx
23
+ // Next.js Pages: pages/_app.tsx
24
+ // Vite / Figma Make: src/main.tsx
21
25
  import "@sarunyu/system-one/styles.css";
22
26
  ```
23
27
 
24
- Then use components anywhere — no provider or wrapper needed:
28
+ No provider, no wrapper. Components ship with `"use client"`.
29
+
30
+ ## Use
25
31
 
26
32
  ```tsx
27
- import { Button, Input, Tag, TabGroup, Chip } from "@sarunyu/system-one";
33
+ import { Button, Input, Tag, TabGroup } from "@sarunyu/system-one";
28
34
 
29
35
  export default function Example() {
30
36
  return (
31
- <div>
32
- <Button variant="primary" size="md">Get started</Button>
33
- <Button variant="outline" size="md">Learn more</Button>
37
+ <div className="flex flex-col gap-4 p-6">
38
+ <h1>Hello</h1>
39
+ <Input placeholder="Email" />
40
+ <Button variant="primary" size="md">Continue</Button>
34
41
  </div>
35
42
  );
36
43
  }
37
44
  ```
38
45
 
46
+ ## Philosophy — components strict, layout free
47
+
48
+ The library is responsible for **components**: every Button, Input, Tag, Card, etc.
49
+ must come from the library — never hand-rolled from raw HTML + utility classes.
50
+ That keeps the visual language consistent.
51
+
52
+ The library is **not** responsible for **layout**. Design page structure yourself
53
+ using plain `<div>` + Tailwind (`flex`, `grid`, `max-w-*`, `gap-*`). The library
54
+ ships no `Page`/`Section`/`Stack` primitives — use whatever layout looks right.
55
+
39
56
  ## Components
40
57
 
41
- | Component | Description |
58
+ | Component | Purpose |
42
59
  |---|---|
43
- | `Button` | Action button — 6 variants, 10 sizes (label + icon-only) |
44
- | `Input` | Floating-label text input with validation states |
45
- | `TextArea` | Multi-line text input with character counter |
46
- | `SearchInput` | Search field with clear button |
47
- | `Dropdown` | Single-select dropdown |
48
- | `DropdownMultiple` | Multi-select dropdown with checkboxes |
49
- | `Tag` | Compact colored label for status and categories |
50
- | `StatusTag` | Process-state indicator with colored dot |
51
- | `Chip` | Toggleable filter/selection chip |
52
- | `Tab` / `TabGroup` | Tabbed navigation with notification badges |
53
- | `Card` | Responsive event/content card |
54
- | `DateInput` | Calendar date picker (single, range, multiple modes) |
55
- | `TimeInput` | 24-hour time picker |
56
- | `OptionList` | Scrollable option list for custom dropdowns |
57
-
58
- ## Dark Mode
59
-
60
- Add `.dark` class to any ancestor element to activate dark theme:
60
+ | `Button` | Action button — 5 variants, 10 sizes |
61
+ | `Input` / `TextArea` / `SearchInput` | Text input, multiline, search field |
62
+ | `Dropdown` / `DropdownMultiple` / `OptionList` | Select controls |
63
+ | `Checkbox` / `Radio` | Boolean / single-choice |
64
+ | `DateInput` / `TimeInput` | Date and time pickers |
65
+ | `Tag` / `StatusTag` / `Chip` | Labels, workflow states, filter chips |
66
+ | `Tab` / `TabGroup` | Tabbed navigation |
67
+ | `Card` | Event/content card (desktop / tablet / mobile variants) |
68
+ | `Table` | Data tables (`TableRow` / `TableHeaderCell` / `TableCell`) |
69
+
70
+ Full prop reference: [`llms.txt`](./llms.txt).
71
+
72
+ ## Dark mode
73
+
74
+ Add `.dark` to any ancestor:
61
75
 
62
76
  ```tsx
63
- <html className="dark">
77
+ <html className={isDark ? "dark" : ""}>
64
78
  ```
65
79
 
66
- All components adapt automatically.
80
+ All components and tokens adapt.
67
81
 
68
82
  ## Theming
69
83
 
70
- All design tokens are CSS custom properties. Override them after the stylesheet import:
84
+ Override CSS custom properties after importing the stylesheet. **Override
85
+ both `:root` and `.dark` — they are independent blocks.**
86
+
87
+ The hex values below are **placeholders for your brand palette** (shown in
88
+ violet for contrast). They are not part of System One — the library's own
89
+ defaults live in `tokens/color.json` (P1 blue).
71
90
 
72
91
  ```css
92
+ /* Light mode — replace with YOUR brand palette */
73
93
  :root {
74
- --primary-action: #7c3aed; /* brand color */
75
- --primary-action-hover: #6d28d9;
94
+ --primary-action: #7c3aed; /* your brand 600 */
95
+ --primary-action-hover: #6d28d9; /* your brand 700 */
96
+ --primary-action-active: #5b21b6; /* your brand 800 */
76
97
  --font-sans: "Inter", sans-serif;
77
98
  }
99
+
100
+ /* Dark mode — independent; set separately */
101
+ .dark {
102
+ --primary-action: #a78bfa; /* your brand 400 */
103
+ --primary-action-hover: #c4b5fd; /* your brand 300 */
104
+ --primary-action-active: #8b5cf6; /* your brand 500 */
105
+ --primary-action-light: color-mix(in srgb, #a78bfa 10%, transparent);
106
+ --primary-action-muted: color-mix(in srgb, #a78bfa 15%, transparent);
107
+ }
78
108
  ```
79
109
 
80
- Key tokens: `--primary-action`, `--background`, `--foreground`, `--border`, `--muted-foreground`, `--destructive`, `--success`.
110
+ Key tokens: `--primary-action`, `--background`, `--foreground`, `--border`,
111
+ `--muted-foreground`, `--destructive`, `--success`. See [`llms.txt`](./llms.txt)
112
+ for the full token table mapped to Tailwind utility classes.
81
113
 
82
114
  ## TypeScript
83
115
 
84
- Full type definitions included:
116
+ Full types included:
85
117
 
86
118
  ```ts
87
- import type { ButtonVariant, ButtonSize, TagVariant, ChipSize } from "@sarunyu/system-one";
119
+ import type {
120
+ ButtonVariant, ButtonSize,
121
+ TagVariant, ChipSize,
122
+ InputProps, DropdownOption,
123
+ } from "@sarunyu/system-one";
88
124
  ```
89
125
 
90
126
  ## Development
91
127
 
92
128
  ```bash
93
129
  npm install
94
- npm run dev # start demo server
95
- npm run build:lib # build the library
130
+ npm run dev # showcase demo
131
+ npm run build:lib # build the library
96
132
  ```
97
133
 
98
134
  ## License