@sakaniui/mcp 0.0.0-stage → 0.8.10

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