@sakaniui/mcp 0.0.0-stage → 0.8.11

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.
package/data/AGENTS.md ADDED
@@ -0,0 +1,273 @@
1
+ # Sakani UI — guide for AI agents
2
+
3
+ You are building with `@sakaniui/react`. This file is the *why* behind the system: what each
4
+ piece is for, when it is the wrong choice, and what to do when nothing fits. Props and types are
5
+ in the shipped `.d.ts` files; live examples are at https://www.sakaniui.com/docs. Read this file
6
+ first, then open a component's docs page for its props.
7
+
8
+ Full machine-readable index: https://www.sakaniui.com/llms.txt (and `/llms-full.txt`).
9
+
10
+ **The contract:** `@sakaniui/react/manifest.json` (also https://www.sakaniui.com/manifest.json) lists
11
+ every exported component and block with its import path, props, types, enum values, defaults, which
12
+ props are *required*, and every design token. It is generated from the TypeScript source on each
13
+ build, so it is always in step with the installed version. Prefer it over guessing a prop name:
14
+ ```ts
15
+ import manifest from '@sakaniui/react/manifest.json';
16
+ const button = manifest.components.find((c) => c.name === 'Button'); // props[], contract.requiredProps
17
+ ```
18
+ Editors can query the same data through the bundled MCP server
19
+ (`npx -y @sakaniui/mcp`): `search_components`, `get_component`, `search_icons`,
20
+ `check_code`, `check_usage`, `get_tokens`, `get_guide`, `check_compatibility`, `get_changelog`.
21
+
22
+ **Object props have a shape.** A prop such as `columns`, `items`, `options`, `plans` or `data` takes an array
23
+ of objects with exactly the fields listed under the prop's `shape` (required ones must be present, and
24
+ `keyof T` means "a field of your own data type"). `check_code` verifies the field names of inline literals.
25
+ Components with a pattern the types do not teach carry `recipes`: code that compiles.
26
+
27
+ **Start from the example, check before you answer.** Every component has `example`: its imports and the
28
+ element with each required prop filled in, type-checked against the release. Start from it instead of
29
+ writing the element from memory. Never guess an icon name: find it with `search_icons` (icons are
30
+ `IconTrash`, `IconSettings`, ... from `@sakaniui/react/icons`, passed as `icon={IconTrash}`, not
31
+ `icon={<IconTrash />}`). If the server is connected, run `check_code` on every snippet you write.
32
+
33
+ **Versions.** Every component has `since`, the first release that contained it. The project may have an
34
+ older `@sakaniui/react` installed than the one the manifest describes: if an entry is marked
35
+ `availableInInstalled: false`, or `check_compatibility` lists it under `missingInInstalled`, it does not
36
+ exist in that project, so do not use it without upgrading. The server reads the project's installed
37
+ version itself; if it cannot, run `npm ls @sakaniui/react` and pass the result as `installedVersion`.
38
+ If a prop, value or token is not in the manifest, it does not exist. If `contract.requiresAccessibleName`
39
+ is true, the required `aria-label` / alt prop is the only thing that names the control. Do not drop it.
40
+
41
+ ---
42
+
43
+ ## 1. Setup you must get right
44
+
45
+ ```tsx
46
+ import '@sakaniui/react/tokens.css'; // design tokens (CSS variables) — once, at the app root
47
+ import '@sakaniui/react/style.css'; // component styles — once
48
+ import { Button, Card } from '@sakaniui/react';
49
+ ```
50
+
51
+ - **Both CSS imports are required.** Without `tokens.css` every component renders unstyled or
52
+ black-and-white, because every colour, space, radius and shadow is a CSS variable defined there.
53
+ - **Dark mode is a class.** Put `className="dark"` on any container; everything inside re-themes.
54
+ Do not write per-component dark styles.
55
+ - **Surface is a second axis, independent of light/dark:** `data-surface="solid" | "glass" | "liquid"`
56
+ on a container. Components inside adapt. See §4.
57
+
58
+ ## 2. Principles (apply these when a case is not covered)
59
+
60
+ 1. **Tokens, never literals.** Colours, spacing, radius, shadows come from `var(--color-…)`,
61
+ `var(--space-…)`, `var(--radius-…)`. A hex value in your code will not follow dark mode, glass
62
+ surfaces or future theme changes. If you need a colour that has no token, pick the nearest
63
+ semantic token and say so; do not invent a hex.
64
+ 2. **Semantic roles over raw values.** Use `--color-fg-default / -muted / -subtle`, `--color-bg-surface /
65
+ -canvas / -subtle`, `--color-border-subtle / -default / -focus`, `--color-accent-*`. The role says
66
+ what the colour is *for*, which is what survives a re-theme.
67
+ 3. **One primary action per view.** A single filled `primary` Button marks the thing the user most
68
+ likely wants. Two filled buttons compete and make neither primary. Put the second action in
69
+ `secondary` or `outline`, the third in `ghost`.
70
+ 4. **Use the component, don't restyle a `<button>`.** Buttons carry hover, press, focus-visible,
71
+ loading and (on glass) liquid behaviour. A hand-styled `<button>` silently misses every future
72
+ improvement. (Two components shipped with raw buttons and were fixed in 0.4.6 and 0.4.7 for exactly
73
+ this reason.)
74
+ 5. **States are CSS, not props.** Hover, focus-visible and disabled are pseudo-classes. Don't try to
75
+ force a hover state with a prop; none exists. Exceptions are documented presentational states
76
+ (e.g. `BoardCard state="dragging"`).
77
+ 6. **Accessibility is part of the API, not an extra.** Icon-only controls require a label
78
+ (`aria-label`, or `label` on `socialLinks`). Status changes use live regions (`Alert`, `Toast`,
79
+ `Spinner`, `EmptyState` are `role="status"`/`alert`). Never remove focus rings.
80
+ 7. **Don't fake what the system doesn't do.** `Toast` is presentational — you own queueing and
81
+ positioning. `Menu` is a surface — you own anchoring (pair it with `Popover`). Dragging is a
82
+ look, not a behaviour. Check "Behaviour you must supply" in the table below before assuming.
83
+ 8. **Compose in slots, don't fork.** Components expose slots (`leading`, `trailing`, `meta`,
84
+ `assignees`, `icon`, `actions`). Fill a slot with other system components rather than copying a
85
+ component's markup.
86
+
87
+ ## 2b. Token names — use exactly these (anything else does not exist)
88
+
89
+ A CSS variable that isn't defined silently resolves to nothing: no error, just broken spacing or
90
+ colour. Do not guess names (`--fg-muted`, `--bg-canvas`, `--spacing-4` and `--space-3` are all **wrong**).
91
+
92
+ - **Space** — `--space-N` where **N is the pixel value**: `0, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96`. So `--space-6` is 6px (not 24px)
93
+ and `--space-24` is 24px. There is no `--space-3` or `--space-5`.
94
+ - **Text** — `--color-fg-default`, `--color-fg-muted`, `--color-fg-subtle`, `--color-fg-on-accent`,
95
+ `--color-fg-on-inverse`.
96
+ - **Backgrounds** — `--color-bg-canvas` (page), `--color-bg-surface` (cards, panels), `--color-bg-subtle`,
97
+ `--color-bg-muted`, `--color-bg-inverse`.
98
+ - **Borders** — `--color-border-subtle`, `--color-border-default`, `--color-border-strong`,
99
+ `--color-border-focus`.
100
+ - **Brand/status** — `--color-accent-{default,hover,active,subtle,fg}`; for `danger`, `success`,
101
+ `warning`, `info`: `--color-<status>-{bg,border,fg,solid}` plus a 50–950 scale.
102
+ - **Radius** — `--radius-{none,2xs,xs,sm,md,lg,xl,2xl,3xl,full}` (`md` = 8px is the default control radius).
103
+ - **Shadow** — `--shadow-{xs,sm,md,lg,xl,2xl}`. **Font** — `--font-sans`, `--font-mono`.
104
+ **Motion** — `--transition-{fast,base,hover,slow}`.
105
+ - Full, resolved list for light and dark: https://www.sakaniui.com/docs/tokens
106
+
107
+ ## 3. When nothing fits
108
+
109
+ Work down this list and stop at the first that works:
110
+
111
+ 1. **A variant or slot of an existing component** (most "missing" cases are one).
112
+ 2. **Compose two or three existing components** inside a `Card` or a block layout.
113
+ 3. **Compose from tokens** — your own element styled only with `var(--…)` values and system
114
+ components inside. Match the 8px radius (`--radius-md`) and token spacing of neighbours.
115
+ 4. **Say what is missing.** If the need is real and not covered, tell the user plainly
116
+ ("the system has no X; I built Y from tokens") instead of silently approximating. Do not present a
117
+ workaround as a system component.
118
+
119
+ Never: invent props that aren't in the `.d.ts`, import from `dist/` internals, or copy the
120
+ CSS of a component into your own file.
121
+
122
+ ## 4. Glass and Liquid Glass
123
+
124
+ - **`solid`** (default): opaque, crisp. Use for dense data — tables, forms, charts. Reading speed
125
+ beats atmosphere.
126
+ - **`glass`**: frosted translucency. Use for chrome floating over content: sidebars, bars, popovers.
127
+ - **`liquid`**: real refraction that bends what is behind it. Use sparingly, for a few large
128
+ navigational or hero surfaces over a rich image or gradient. It needs something visually
129
+ interesting behind it; over a flat colour it adds cost and nothing else.
130
+ - **Don't put data inside liquid.** Keep tables, inputs and charts on `data-surface="solid"` inside a
131
+ liquid layout so numbers stay legible.
132
+ - **Refraction renders in Chromium only.** Safari and Firefox get a frosted fallback with the same rim.
133
+ Design so the fallback is acceptable, not broken. Use `refraction="off"` to preview the fallback.
134
+ - **Cost is per lens.** Each liquid surface runs an SVG filter. Dozens on one screen will lag; a
135
+ handful is fine. Large static lenses are baked to a canvas automatically (`bake`).
136
+ - **`LiquidBackdrop` supplies what is behind the lens.** A lens needs a backdrop to refract; wrap
137
+ the photo/gradient in `LiquidBackdrop`.
138
+
139
+ ## 4c. Icons
140
+
141
+ - The icon set is Tabler Icons. Import from `@sakaniui/react/icons`: `IconHome`, `IconCalendar` ... (outline,
142
+ 5,184) and `IconHomeFilled` ... (filled, 1,054). Names follow Tabler (tabler.io/icons is the search),
143
+ kebab-case to `Icon` + PascalCase, `Filled` suffix for filled. Each is tree-shaken on its own.
144
+ - Outline for normal UI; Filled for active/selected states (a selected nav item, a liked heart). Don't
145
+ mix the two in one row without a reason: filled means "on".
146
+ - Props follow lucide-react: `size` (default 24), `color` (default currentColor), `strokeWidth` (default
147
+ 1.5, the Figma icon stroke), `absoluteStrokeWidth`. Add `title` when the icon carries meaning alone.
148
+ - Component props that take an icon (`icon`, `leftIcon` ...) take the component itself, typed
149
+ `IconComponent`; Sakani, Lucide and Tabler React icons all fit.
150
+
151
+ ## 5. Component guide — what it's for, why it behaves that way, when not to use it
152
+
153
+ Format: **Use for** · **Why it is built this way** · **Not for / instead**.
154
+
155
+ ### Actions
156
+ - **Button** — Use for any action that does something. *Why:* 5 variants × 3 sizes mirror Figma 1:1;
157
+ `loading` disables interaction so double-submits can't happen. *Not for* navigation → `Link`; icon-only →
158
+ `IconButton`. One `primary` per view.
159
+ - **IconButton** — Use for compact, recognisable actions (close, more, add). *Why:* square, same variant
160
+ logic as Button, and `aria-label` is required because a glyph alone is unusable with a screen reader.
161
+ *Not for* anything whose icon isn't universally obvious → `Button` with a label.
162
+ - **Link** — Use for navigation. *Why:* a link goes somewhere, a button does something; mixing them breaks
163
+ keyboard and assistive-tech expectations.
164
+
165
+ ### Status and feedback
166
+ - **Alert** — Use for a message that belongs to the page or a section and stays until resolved.
167
+ *Not for* transient confirmation → `Toast`.
168
+ - **Toast** — Use for short-lived confirmation or error after an action. *Why:* presentational only;
169
+ queueing and positioning are the app's job, so it fits any notification system. *Not for* anything the user
170
+ must act on — a toast disappears.
171
+ - **Badge** — Use for a short status, category or count. *Why:* 6 colours × subtle/solid, no sizes, no
172
+ borders — it is a label, not a control. *Not for* clickable filters → `FilterChip`.
173
+ - **Tooltip** — Use for brief supplementary text on hover/focus. *Why:* pure CSS, so it works with
174
+ keyboard focus. *Not for* essential information (touch users never see hover) or interactive content →
175
+ `Popover`.
176
+ - **Spinner / Progress / Skeleton** — Spinner: an action is running, unknown length. Progress: known
177
+ completion (give `value`) or an indeterminate page load (omit it). Skeleton: the *shape* of content that is
178
+ about to appear. *Why:* a skeleton keeps layout stable and tells the user what is coming; a spinner only
179
+ says "wait". Prefer Skeleton for first-load of lists/cards.
180
+ - **EmptyState** — Use when a list, table or panel has nothing to show. *Why three types:* `no-data`
181
+ (nothing exists → action is to create), `no-results` (a filter hides things → relax the filter),
182
+ `error` (request failed → retry). They are different situations needing different actions; one generic
183
+ message wastes the moment. Override `title`/`description` with specifics wherever possible.
184
+
185
+ ### Forms
186
+ - **Input / Textarea / Select / Combobox** — Input: free text. Select: choose one from a short fixed list
187
+ (it is a custom listbox, not native `<select>`, so the open state matches the design). Combobox: search a
188
+ long list or pick several (multi, with chips). *Why:* choosing the lightest control that fits keeps forms
189
+ fast; don't use a Combobox for four options.
190
+ - **Checkbox / Radio / Switch** — Checkbox: independent yes/no, or multiple choices. Radio: exactly one of a
191
+ few (give them a shared `name`). Switch: an immediate on/off that takes effect now; a checkbox is for
192
+ things applied on submit.
193
+ - **SegmentedControl** — Use to switch between 2–6 views or modes of the *same* content. *Not for*
194
+ navigation between pages → `Tabs`.
195
+ - **FileUpload / AvatarUpload** — Use for files / profile photos respectively.
196
+ - **Always give inputs a visible label** (`Input` has one built in). Placeholders are not labels.
197
+
198
+ ### Navigation
199
+ - **Sidebar family** (`Sidebar`, `SidebarItem`, …) — Use for app-level navigation. Expanded 248px,
200
+ collapsed 64px. Compose the parts; don't build a sidebar from scratch.
201
+ - **TopBar** — Use beside the sidebar for search, breadcrumb, tabs, or chat context. Slots (`left`,
202
+ `actions`, `account`) are composed by the caller.
203
+ - **Tabs** — Switch between peer panels in one place. **Breadcrumb** — show where a deep page sits.
204
+ **Pagination** — move through pages of a long list. **Stepper** — a fixed multi-step flow; completed /
205
+ current / upcoming states; motion is choreographed on step change.
206
+ - **Menu** — a list of actions in a surface; *you* anchor it (pair with `Popover`). **Popover** — floating
207
+ panel on click; closes on outside click or Escape.
208
+ - **Modal** — Use only when the task genuinely must interrupt (confirm destructive action, short focused
209
+ form). Anything the user might want to refer back to the page for → `Popover` or inline.
210
+
211
+ ### Content and data
212
+ - **Card** — a container surface for a unit of content, optionally with actions. Not a layout wrapper for
213
+ everything.
214
+ - **Table** — dense, comparable records. `Table<T>` is generic: every column's `key` must be a field of
215
+ your row type `T` (`keyof T & string`), so a column that is not data (a delete button, a menu) still
216
+ needs a key: give the row type an optional `never` field (`actions?: never`) and render the control in
217
+ `render`. Inventing a key that is not on the row type does not compile (see `recipes` in
218
+ `get_component("Table")` for code that does). **StatCard** — one headline metric with trend. **ListItem** — a
219
+ row in a list. **Charts** — pick by question: trend over time → Line/Area; compare categories → Bar;
220
+ part of whole → Pie/Donut (few slices only); progress to a target → Radial; compare several measures →
221
+ Radar; drop-off → Funnel; intensity across two dimensions → Heatmap.
222
+ - **Avatar / AvatarGroup** — Avatar type is inferred: `src` → image, `initials` → initials, else icon.
223
+ Prefer a real image when you have one; initials are the fallback, not the default.
224
+ - **BoardCard / BoardColumn** — kanban pieces. `BoardColumn state="loading"` styles the column; *you* pass
225
+ Skeleton-filled `BoardCard`s as children. `state="dragging"` only styles; implement drag yourself.
226
+ - **ProfileCard / TeamCard** — ProfileCard: compact (row) or detailed (centred, with bio/social). TeamCard:
227
+ portrait-led with a location bar. Both want a real photo.
228
+
229
+ ### Blocks
230
+ Blocks (`CRMDashboardBlock`, `DataTableBlock`, `KanbanBoardBlock`, `LoginBlock`, …) are composed
231
+ screens, not primitives. Use one when it matches the screen you are building; otherwise compose primitives.
232
+ Many Figma-frame blocks have a fixed design width — put them in a container at least that wide or scale them.
233
+
234
+ ## 6. Moments an AI product needs (compose these today)
235
+
236
+ The system has no dedicated AI components yet. Until it does, build these moments from existing parts,
237
+ and **tell the user when you are composing** rather than implying a dedicated component exists.
238
+
239
+ - **The model isn't sure.** State uncertainty in words next to the claim, not hidden in colour. Use an
240
+ `Alert` (`color="info"` or `"warning"`) or a `Badge` ("Low confidence"). Offer the next step: verify,
241
+ rephrase, or ask for more context.
242
+ - **Showing a source.** Attach sources to the claim they support, as `Link`s or `Tags`/`Badge`s with a
243
+ visible domain or title. A claim without a reachable source should look different from one with it.
244
+ - **A request that will not be completed.** Say what was declined and why in plain language, then what
245
+ *can* be done. Use `Alert` (not an error toast — the user did nothing wrong) plus an alternative action
246
+ as a `secondary` Button.
247
+ - **A response that is only half there.** Streaming or partial: show `Skeleton` or a `Spinner` for the
248
+ missing remainder, keep what has arrived, and make interruption possible. Never present a truncated
249
+ answer as complete; mark it ("Response cut off") and offer retry. Use `EmptyState type="error"` only
250
+ when nothing usable arrived.
251
+ - **Chat.** `MessageBubble`, `ConversationItem`, `ChatComposer` cover the shell. Keep the composer
252
+ reachable while a response is streaming.
253
+
254
+ ## 7. Behaviour you must supply (the system will not do these)
255
+
256
+ | Component | You own |
257
+ |---|---|
258
+ | Toast | queueing, positioning, auto-dismiss timing |
259
+ | Menu | anchoring/positioning (pair with Popover) |
260
+ | BoardCard `dragging` | drag-and-drop logic and drop targets |
261
+ | BoardColumn `loading` | the skeleton cards inside it |
262
+ | Blocks | data fetching and state; they are presentational |
263
+ | LiquidGlass | a backdrop worth refracting (`LiquidBackdrop`) |
264
+
265
+ ## 8. Checklist before you finish
266
+
267
+ - [ ] Both CSS files imported once; no hex/px literals where a token exists.
268
+ - [ ] Exactly one `primary` Button per view; no hand-styled `<button>`.
269
+ - [ ] Every icon-only control has an accessible name.
270
+ - [ ] Every prop, value and token you used exists in `manifest.json`; every `contract.requiredProps` entry is set.
271
+ - [ ] Looks right inside `className="dark"`.
272
+ - [ ] If you used glass/liquid: acceptable in the frosted fallback; data surfaces stay `solid`.
273
+ - [ ] You said so wherever you composed something the system doesn't provide.