@tailor-platform/app-shell 1.10.1 → 1.12.0
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/README.md +1 -0
- package/dist/app-shell-core.css +1 -1
- package/dist/app-shell.d.ts +273 -55
- package/dist/app-shell.js +7400 -6147
- package/dist/theme-bridge.test.ts +59 -0
- package/dist/theme.bridge.css +21 -0
- package/package.json +14 -14
- package/skills/app-shell-patterns/SKILL.md +7 -1
- package/skills/app-shell-patterns/references/fundamental/components.md +3 -3
- package/skills/app-shell-patterns/references/fundamental/design-system.md +216 -162
- package/skills/app-shell-patterns/references/migrations.md +167 -0
- package/skills/app-shell-patterns/references/patterns/form-wizard.md +5 -3
- package/skills/app-shell-patterns/references/patterns/interaction-multi-select.md +1 -1
|
@@ -1,127 +1,176 @@
|
|
|
1
1
|
# Design System
|
|
2
2
|
|
|
3
|
-
Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent,
|
|
3
|
+
Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, the `astw:` prefix, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
|
|
4
4
|
|
|
5
|
-
`@tailor-platform/app-shell`
|
|
5
|
+
`@tailor-platform/app-shell` ships an opinionated design system as CSS variables, bridged into Tailwind v4's token namespace. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
|
|
6
6
|
|
|
7
|
-
**The tokens are the rails.** Consistency across customers, apps, and AI runs comes from the token system, not from rules written in prose. A hand-typed `#fff` or `padding: 13px` is not a "small deviation" — it is the mechanism by which consistency dies.
|
|
7
|
+
**The tokens are the rails.** Consistency across customers, apps, and AI runs comes from the token system, not from rules written in prose. A hand-typed `#fff` or `padding: 13px` is not a "small deviation" — it is the mechanism by which consistency dies.
|
|
8
|
+
|
|
9
|
+
**Every token in this file is verified against the shipped CSS.** If a token is not listed here, assume it does not exist. Inventing a plausible-sounding token (`bg-surface-1`, `text-fg-muted`, `--space-4`) is the worst failure mode available to you: Tailwind emits **no CSS at all** for an unknown utility, so the class is silently dropped and the element renders unstyled. There is no error, no warning, and nothing in the console. When unsure, read `node_modules/@tailor-platform/app-shell/dist/themes/default.css` — it is the ground truth.
|
|
8
10
|
|
|
9
11
|
## 1. Setup
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
The app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
|
|
12
14
|
|
|
13
15
|
```css
|
|
14
16
|
@import "tailwindcss";
|
|
15
|
-
@import "tw-animate-css";
|
|
16
|
-
|
|
17
17
|
@import "@tailor-platform/app-shell/styles";
|
|
18
|
-
@import "@tailor-platform/app-shell/theme.css";
|
|
19
|
-
```
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
/* Optional: at most one palette override, imported AFTER styles */
|
|
20
|
+
@import "@tailor-platform/app-shell/themes/bloom";
|
|
21
|
+
```
|
|
22
22
|
|
|
23
|
-
- `**
|
|
24
|
-
- `**
|
|
25
|
-
-
|
|
23
|
+
- **`tailwindcss`** — your app's own Tailwind build, which generates the utilities you write in your components.
|
|
24
|
+
- **`@tailor-platform/app-shell/styles`** — the single required import. It pulls in both the design tokens (the `@theme inline` bridge, so `bg-background` / `text-muted-foreground` resolve in _your_ Tailwind build) and AppShell's precompiled component CSS.
|
|
25
|
+
- **`@tailor-platform/app-shell/themes/*`** — optional palette overrides (`default`, `cream`, `bloom`). Import at most one, after `styles`. Palette selection is by CSS import; there is no runtime palette prop.
|
|
26
26
|
|
|
27
|
-
Older docs referred to `app-shell.css`; prefer
|
|
27
|
+
**Do not import `@tailor-platform/app-shell/theme.css`.** That export is a deprecated no-op shim, kept only so older apps keep building. It emits nothing. Older docs also referred to `app-shell.css`; prefer `styles`.
|
|
28
28
|
|
|
29
|
-
Tailwind v4 stays CSS-first; minimal `vite` / PostCSS wiring is in
|
|
29
|
+
Tailwind v4 stays CSS-first; minimal `vite` / PostCSS wiring is in `project-setup.md`.
|
|
30
30
|
|
|
31
31
|
## 2. Theming via CSS variables
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Tokens exist in two layers, and knowing which one you are touching matters:
|
|
34
|
+
|
|
35
|
+
1. **Raw CSS variables** (`--background`, `--primary`, `--radius`) — defined on `:root` in `themes/*.css`. These are what you **override**.
|
|
36
|
+
2. **The Tailwind bridge** (`@theme inline` in `theme.bridge.css`) — maps each raw variable into Tailwind's namespace (`--background` → `--color-background`), which is what makes `bg-background` a real utility. You do **not** edit this layer.
|
|
37
|
+
|
|
38
|
+
Override raw variables after the `styles` import, using `:root` for light and `:root.dark` for dark. Set every override in both modes — overriding just `:root` misbehaves either way: on the default palette the light value carries into dark mode, and on a branded palette the override stops applying in dark mode altogether.
|
|
34
39
|
|
|
35
40
|
```css
|
|
36
41
|
:root {
|
|
37
|
-
--
|
|
38
|
-
--color-background: #ffffff;
|
|
42
|
+
--primary: #3b82f6;
|
|
39
43
|
}
|
|
40
44
|
|
|
41
|
-
|
|
42
|
-
--
|
|
43
|
-
--color-foreground: #fafafa;
|
|
45
|
+
:root.dark {
|
|
46
|
+
--primary: #60a5fa;
|
|
44
47
|
}
|
|
45
48
|
```
|
|
46
49
|
|
|
47
|
-
|
|
50
|
+
Use `:root.dark`, not a bare `.dark`. The default palette is imported inside a cascade layer (`layer(theme.defaults)`), so any unlayered declaration of yours beats it — but the branded palettes (`cream`, `bloom`) are imported unlayered and define their dark values on `:root.dark`, which outranks `.dark`. A `.dark` override would silently lose against those.
|
|
51
|
+
|
|
52
|
+
Override at the highest scope where the change applies. A narrower scope (per-section, per-tenant) needs the same both-modes treatment, and its dark rule must still outrank a branded palette's `:root.dark` — pair `.tenant-a` with `:root.dark .tenant-a`. Do not duplicate token values across files — change them at the source. Never copy the palette wholesale; tokens you did not copy stay on AppShell's values, so the two halves drift apart and any surface AppShell adds later has no value in the copy at all.
|
|
48
53
|
|
|
49
|
-
**
|
|
54
|
+
**Do not paste a `@theme inline` block, a `@custom-variant dark` rule, or a copy of AppShell's palette into the app's entry CSS.** `styles` provides all three. A copy of any of them in the app's own CSS is unlayered, so it beats AppShell's layered palette and silently breaks dark mode — the build succeeds and nothing warns.
|
|
55
|
+
|
|
56
|
+
**Dark mode is a `.dark` class on `<html>`**, not a data attribute. AppShell's theme provider toggles `document.documentElement.classList` between `light` and `dark` and persists the choice under the `appshell-ui-theme` localStorage key; the bundled `AppearanceSwitcher` component drives it. The bridge registers `@custom-variant dark (&:where(.dark, .dark *))`, so the `dark:` variant works in your own markup.
|
|
57
|
+
|
|
58
|
+
AppShell primitives respond to dark mode automatically. Custom components inherit it for free as long as they reference tokens (`bg-card`, `text-muted-foreground`) and never inline literal colors.
|
|
50
59
|
|
|
51
60
|
## 3. Component styling with data attributes
|
|
52
61
|
|
|
53
|
-
AppShell's UI components support data-attribute-based styling, following the [Base UI data attributes](https://base-ui.com/react/handbook/styling#data-attributes) convention. Components expose `data
|
|
62
|
+
AppShell's UI components support data-attribute-based styling, following the [Base UI data attributes](https://base-ui.com/react/handbook/styling#data-attributes) convention. Components expose `data-*` attributes that reflect their internal state, enabling CSS-only style control without JavaScript:
|
|
54
63
|
|
|
55
64
|
```css
|
|
56
65
|
/* Style a component based on its state */
|
|
57
66
|
.SwitchThumb[data-checked] {
|
|
58
|
-
background-color:
|
|
67
|
+
background-color: var(--status-completed);
|
|
59
68
|
}
|
|
60
69
|
|
|
61
70
|
.MenuItem[data-highlighted] {
|
|
62
|
-
background-color: var(--
|
|
63
|
-
color:
|
|
71
|
+
background-color: var(--accent);
|
|
72
|
+
color: var(--accent-foreground);
|
|
64
73
|
}
|
|
65
74
|
```
|
|
66
75
|
|
|
67
76
|
This works with Tailwind as well — **use theme tokens**, not raw Tailwind grays:
|
|
68
77
|
|
|
69
78
|
```tsx
|
|
70
|
-
<Switch.Thumb className="bg-
|
|
79
|
+
<Switch.Thumb className="bg-muted data-[checked]:bg-primary" />
|
|
71
80
|
```
|
|
72
81
|
|
|
73
82
|
Check each component's API reference (`components.md`) for the data attributes it exposes. Custom components must follow the same convention (see Section 6).
|
|
74
83
|
|
|
75
84
|
## 4. Tokens
|
|
76
85
|
|
|
77
|
-
|
|
86
|
+
Everything below is verified present in the shipped CSS. **Use the token, never hand-type the value.** A hex literal or magic px in a PR is a review failure.
|
|
78
87
|
|
|
79
88
|
### Color
|
|
80
89
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
90
|
+
Colors follow shadcn-style semantic naming: a surface token and its matching `-foreground` pair. Pick by **intent**, not by visual taste. Pair a background with its own foreground — `bg-card` goes with `text-card-foreground`.
|
|
91
|
+
|
|
92
|
+
#### Surface & chrome
|
|
93
|
+
|
|
94
|
+
| Token | Use | Tailwind |
|
|
95
|
+
| ------------------------------------ | ----------------------------- | ---------------------------------------- |
|
|
96
|
+
| `--background` / `--foreground` | page background, default text | `bg-background` / `text-foreground` |
|
|
97
|
+
| `--card` / `--card-foreground` | card and panel surfaces | `bg-card` / `text-card-foreground` |
|
|
98
|
+
| `--popover` / `--popover-foreground` | menus, popovers, tooltips | `bg-popover` / `text-popover-foreground` |
|
|
99
|
+
| `--muted` / `--muted-foreground` | subtle fills; secondary text | `bg-muted` / `text-muted-foreground` |
|
|
100
|
+
| `--border` | hairlines, dividers | `border-border` |
|
|
101
|
+
| `--input` | form control borders | `border-input` |
|
|
102
|
+
| `--ring` | focus rings | `ring-ring` / `outline-ring` |
|
|
103
|
+
|
|
104
|
+
Surfaces are named by **role**, not by depth — there is no numbered `surface-1/2/3` ladder, and no third tier of body text below `muted-foreground`. Stack depth with `background` → `card` → `muted` plus a border or shadow, and reach for `popover` when the surface actually floats.
|
|
105
|
+
|
|
106
|
+
#### Brand & action
|
|
107
|
+
|
|
108
|
+
| Token | Use | Tailwind |
|
|
109
|
+
| -------------------------------------------- | -------------------------------- | -------------------------------------------- |
|
|
110
|
+
| `--primary` / `--primary-foreground` | primary buttons, emphasis | `bg-primary` / `text-primary-foreground` |
|
|
111
|
+
| `--secondary` / `--secondary-foreground` | secondary buttons, neutral chips | `bg-secondary` / `text-secondary-foreground` |
|
|
112
|
+
| `--accent` / `--accent-foreground` | hover and selected nav states | `bg-accent` / `text-accent-foreground` |
|
|
113
|
+
| `--destructive` / `--destructive-foreground` | destructive actions, errors | `bg-destructive` / `text-destructive` |
|
|
114
|
+
|
|
115
|
+
There are no `-hover` or `-active` brand tokens. Express interaction states with Tailwind variants and opacity — `hover:bg-primary/90`, `active:bg-primary/80` — which is what AppShell's own components do.
|
|
116
|
+
|
|
117
|
+
#### Status
|
|
118
|
+
|
|
119
|
+
Five status colors, used for badge fills and status dots:
|
|
120
|
+
|
|
121
|
+
| Token | Use | Tailwind |
|
|
122
|
+
| -------------------- | ------------------------ | --------------------- |
|
|
123
|
+
| `--status-default` | none / not applicable | `bg-status-default` |
|
|
124
|
+
| `--status-neutral` | informational | `bg-status-neutral` |
|
|
125
|
+
| `--status-completed` | success, completed | `bg-status-completed` |
|
|
126
|
+
| `--status-attention` | warning, needs attention | `bg-status-attention` |
|
|
127
|
+
| `--status-danger` | error, blocked | `bg-status-danger` |
|
|
128
|
+
|
|
129
|
+
Prefer `Badge` with a semantic variant (`success`, `warning`, `error`, `info`, `neutral`) over applying these directly — the variants already pair fill and foreground correctly. Reach for the raw token only on custom surfaces.
|
|
130
|
+
|
|
131
|
+
#### Sidebar & charts
|
|
132
|
+
|
|
133
|
+
`--sidebar`, `--sidebar-foreground`, `--sidebar-border`, `--sidebar-primary(-foreground)`, `--sidebar-accent(-foreground)`, `--sidebar-ring` → `bg-sidebar`, `text-sidebar-foreground`, and so on. These let a palette tint the shell independently of page content.
|
|
134
|
+
|
|
135
|
+
`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series.
|
|
136
|
+
|
|
137
|
+
#### Alerts
|
|
138
|
+
|
|
139
|
+
`--alert-{neutral,success,warning,error,info}-{background,foreground,foreground-muted,border}` — five variants × four slots, each bridged into Tailwind:
|
|
140
|
+
|
|
141
|
+
| Slot | Tailwind | Use for |
|
|
142
|
+
| ------------------ | ---------------------------------- | -------------------------- |
|
|
143
|
+
| `background` | `bg-alert-info-background` | Callout fill |
|
|
144
|
+
| `foreground` | `text-alert-info-foreground` | Primary text and icons |
|
|
145
|
+
| `foreground-muted` | `text-alert-info-foreground-muted` | Secondary/description text |
|
|
146
|
+
| `border` | `border-alert-info-border` | Callout border |
|
|
147
|
+
|
|
148
|
+
Prefer the `Alert` component — it already pairs the four slots per variant and supplies the icon. Reach for the utilities directly only on custom surfaces `Alert` doesn't cover, such as a status-highlighted table row or an inline note:
|
|
98
149
|
|
|
99
150
|
```tsx
|
|
100
|
-
|
|
101
|
-
|
|
151
|
+
<div className="rounded-lg border bg-alert-warning-background text-alert-warning-foreground border-alert-warning-border">
|
|
152
|
+
…
|
|
153
|
+
</div>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The `background` and `border` slots are already semi-transparent tints (~10% and ~20%), so an opacity modifier compounds rather than replaces — `bg-alert-info-background/50` lands near 5% alpha, not 50%.
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
// Good — semantic token pairs, and a variant where one exists
|
|
160
|
+
<div className="bg-card text-card-foreground">…</div>
|
|
102
161
|
<Button variant="destructive">Delete</Button>
|
|
162
|
+
<Badge variant="warning">Pending review</Badge>
|
|
103
163
|
|
|
104
164
|
// Bad — raw colors bypass the theme
|
|
105
165
|
<div style={{ background: "#fff", color: "#111" }}>…</div>
|
|
106
|
-
```
|
|
107
166
|
|
|
108
|
-
|
|
167
|
+
// Bad — these classes do not exist and render as nothing at all
|
|
168
|
+
<div className="bg-surface-1 text-fg-muted">…</div>
|
|
169
|
+
```
|
|
109
170
|
|
|
110
171
|
### Spacing
|
|
111
172
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
| Token | Value | Common use |
|
|
115
|
-
| ------------ | ----- | ------------------------- |
|
|
116
|
-
| `--space-0` | 0 | reset |
|
|
117
|
-
| `--space-1` | 4px | tight icon-text gap |
|
|
118
|
-
| `--space-2` | 8px | inline gap, small padding |
|
|
119
|
-
| `--space-3` | 12px | row gap, button padding |
|
|
120
|
-
| `--space-4` | 16px | card padding, default gap |
|
|
121
|
-
| `--space-6` | 24px | section gap |
|
|
122
|
-
| `--space-8` | 32px | major section gap |
|
|
123
|
-
| `--space-12` | 48px | page section break |
|
|
124
|
-
| `--space-16` | 64px | hero spacing |
|
|
173
|
+
**AppShell defines no spacing tokens.** Use Tailwind's default 4px-based scale (`p-4`, `gap-2`, `mt-8`) — the same scale AppShell's own components use internally. There is no `--space-*` variable.
|
|
125
174
|
|
|
126
175
|
```tsx
|
|
127
176
|
// Good — scale step
|
|
@@ -135,106 +184,112 @@ Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if noth
|
|
|
135
184
|
|
|
136
185
|
### Typography
|
|
137
186
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
| `
|
|
145
|
-
|
|
|
146
|
-
|
|
|
147
|
-
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
187
|
+
**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable) → `font-sans`, which the base layer already applies to `body`.
|
|
188
|
+
|
|
189
|
+
Compose roles from stock Tailwind utilities. These pairings are what AppShell's own components use — match them so your screens sit consistently alongside the primitives:
|
|
190
|
+
|
|
191
|
+
| Role | Utilities |
|
|
192
|
+
| --------------------------------- | ----------------------------------------- |
|
|
193
|
+
| Page title (`Layout.Header`) | `text-2xl font-bold tracking-tight` |
|
|
194
|
+
| Section heading | `text-lg font-semibold` |
|
|
195
|
+
| Card title | `text-lg font-semibold leading-none` |
|
|
196
|
+
| Body copy | `text-sm` |
|
|
197
|
+
| Secondary copy, descriptions | `text-sm text-muted-foreground` |
|
|
198
|
+
| Caption, timestamp, metadata | `text-xs text-muted-foreground` |
|
|
199
|
+
| Numeric value in a table or field | `text-sm font-medium tabular-nums` |
|
|
200
|
+
| ID, code, keyboard hint | `font-mono text-xs text-muted-foreground` |
|
|
152
201
|
|
|
153
202
|
```tsx
|
|
154
|
-
<h2 className="text-
|
|
155
|
-
<p className="text-
|
|
156
|
-
<span className="text-
|
|
203
|
+
<h2 className="text-lg font-semibold">Section</h2>
|
|
204
|
+
<p className="text-sm text-muted-foreground">Description copy</p>
|
|
205
|
+
<span className="text-xs text-muted-foreground">Updated 2h ago</span>
|
|
157
206
|
```
|
|
158
207
|
|
|
208
|
+
Always use `tabular-nums` for numbers that stack in a column — without it, digits jitter between rows.
|
|
209
|
+
|
|
159
210
|
### Radius
|
|
160
211
|
|
|
161
|
-
Pick by component role
|
|
212
|
+
`--radius` (`0.625rem`) is the base; the bridge derives four steps from it. Pick by component role — a card is always `md`, regardless of its size on screen.
|
|
162
213
|
|
|
163
|
-
| Token
|
|
164
|
-
|
|
|
165
|
-
| `--radius-sm`
|
|
166
|
-
| `--radius-md`
|
|
167
|
-
| `--radius-lg`
|
|
168
|
-
| `--radius-xl`
|
|
169
|
-
| `--radius-full` | pills, avatars |
|
|
214
|
+
| Token | Value | Use | Tailwind |
|
|
215
|
+
| ------------- | -------------- | ------------------- | ------------ |
|
|
216
|
+
| `--radius-sm` | `radius − 4px` | inputs, small chips | `rounded-sm` |
|
|
217
|
+
| `--radius-md` | `radius − 2px` | buttons, cards | `rounded-md` |
|
|
218
|
+
| `--radius-lg` | `radius` | modals, sheets | `rounded-lg` |
|
|
219
|
+
| `--radius-xl` | `radius + 4px` | large surfaces | `rounded-xl` |
|
|
170
220
|
|
|
171
|
-
|
|
221
|
+
`rounded-full` (pills, avatars) is a stock Tailwind utility — there is no `--radius-full` token, but the class works.
|
|
172
222
|
|
|
173
|
-
|
|
223
|
+
Changing `--radius` alone rescales all four steps together.
|
|
174
224
|
|
|
175
|
-
|
|
176
|
-
| --------------- | ------------------------ |
|
|
177
|
-
| `--elevation-0` | flat surface |
|
|
178
|
-
| `--elevation-1` | persistent panel, card |
|
|
179
|
-
| `--elevation-2` | sticky bar, hovered card |
|
|
180
|
-
| `--elevation-3` | popover, menu |
|
|
181
|
-
| `--elevation-4` | modal, dialog, sheet |
|
|
225
|
+
### Shadow
|
|
182
226
|
|
|
183
|
-
|
|
227
|
+
Four mode-aware shadows. There are **no `--elevation-*` tokens**; the scale is expressed as shadows. Never hand-craft a `box-shadow`.
|
|
184
228
|
|
|
185
|
-
|
|
229
|
+
| Token | Bridged to | Use |
|
|
230
|
+
| ---------------------- | ----------- | --------------------------------- |
|
|
231
|
+
| `--semantic-shadow-xs` | `shadow-xs` | hairline lift, active nav item |
|
|
232
|
+
| `--semantic-shadow-sm` | `shadow-sm` | cards, persistent panels |
|
|
233
|
+
| `--semantic-shadow-md` | `shadow-md` | popovers, menus, hovered surfaces |
|
|
234
|
+
| `--semantic-shadow-lg` | `shadow-lg` | modals, dialogs, sheets |
|
|
186
235
|
|
|
187
|
-
|
|
188
|
-
| ----------------- | --------- | ------------------------------ |
|
|
189
|
-
| `--motion-fast` | 120ms | hover, focus, button press |
|
|
190
|
-
| `--motion-base` | 200ms | state changes (toggle, select) |
|
|
191
|
-
| `--motion-slow` | 320ms | entrance, dialog open |
|
|
192
|
-
| `--motion-slower` | 500ms | full-page transitions |
|
|
193
|
-
| `--ease-out` | — | entrances, reveals |
|
|
194
|
-
| `--ease-in-out` | — | symmetric state changes |
|
|
236
|
+
Higher shadow reads as "more transient" — match it to the component's lifetime. Each token carries a different value in dark mode, so using the token (rather than a literal) is what keeps depth legible on both backgrounds.
|
|
195
237
|
|
|
196
|
-
|
|
197
|
-
.menu-item {
|
|
198
|
-
transition: background-color var(--motion-fast) var(--ease-out);
|
|
199
|
-
}
|
|
238
|
+
### Motion
|
|
200
239
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
240
|
+
**AppShell defines no motion tokens.** There is no `--motion-fast` or `--ease-out` variable. Use Tailwind's `duration-*` and `ease-*` utilities. AppShell uses `tw-animate-css` internally for its own enter/exit animations, but those classes are prefixed and are not available to your app — add `@import "tw-animate-css";` to your own entrypoint if you want them.
|
|
241
|
+
|
|
242
|
+
| Intent | Utilities |
|
|
243
|
+
| ----------------------------- | -------------------------- |
|
|
244
|
+
| Hover, focus, button press | `duration-150 ease-out` |
|
|
245
|
+
| State change (toggle, select) | `duration-200 ease-in-out` |
|
|
246
|
+
| Entrance, dialog open | `duration-300 ease-out` |
|
|
247
|
+
|
|
248
|
+
```tsx
|
|
249
|
+
<div className="transition-colors duration-150 ease-out motion-reduce:transition-none" />
|
|
206
250
|
```
|
|
207
251
|
|
|
208
|
-
Always
|
|
252
|
+
Always give motion a reduced-motion escape (`motion-reduce:transition-none`, or a `@media (prefers-reduced-motion: reduce)` block in CSS). AppShell components handle this internally; custom components must do the same.
|
|
209
253
|
|
|
210
254
|
### Z-index
|
|
211
255
|
|
|
212
|
-
|
|
256
|
+
These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-sidebar` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
|
|
213
257
|
|
|
214
258
|
| Token | Value | Use |
|
|
215
259
|
| ------------------ | ----- | ----------------------------- |
|
|
216
260
|
| `--z-sidebar` | 10 | persistent sidebar |
|
|
217
|
-
| `--z-sidebar-rail` |
|
|
261
|
+
| `--z-sidebar-rail` | 20 | sidebar collapsed rail |
|
|
218
262
|
| `--z-popup` | 50 | menu, tooltip, popover |
|
|
219
263
|
| `--z-overlay` | 50 | modal, sheet, dialog backdrop |
|
|
220
264
|
|
|
221
|
-
|
|
265
|
+
```tsx
|
|
266
|
+
<div className="z-50" />
|
|
267
|
+
<div className="z-[var(--z-popup)]" />
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation.
|
|
222
271
|
|
|
223
|
-
|
|
272
|
+
### Icons
|
|
224
273
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
|
228
|
-
|
|
|
229
|
-
|
|
|
230
|
-
|
|
|
274
|
+
**AppShell exports no `Icon` component and defines no `--icon-*` tokens.** Icons come from [`lucide-react`](https://lucide.dev), which AppShell already depends on. Size them with Tailwind, pairing icon size to the adjacent text:
|
|
275
|
+
|
|
276
|
+
| Text size | Icon class |
|
|
277
|
+
| ------------------ | ---------- |
|
|
278
|
+
| `text-xs` | `size-3` |
|
|
279
|
+
| `text-sm` | `size-4` |
|
|
280
|
+
| `text-lg` | `size-5` |
|
|
281
|
+
| `text-2xl` (title) | `size-6` |
|
|
231
282
|
|
|
232
283
|
```tsx
|
|
233
|
-
|
|
284
|
+
import { Check } from "lucide-react";
|
|
285
|
+
|
|
286
|
+
<Check className="size-4" />;
|
|
234
287
|
```
|
|
235
288
|
|
|
236
289
|
### Breakpoints
|
|
237
290
|
|
|
291
|
+
Stock Tailwind breakpoints — AppShell does not change them.
|
|
292
|
+
|
|
238
293
|
| Token | Width |
|
|
239
294
|
| ----- | ------ |
|
|
240
295
|
| `sm` | 640px |
|
|
@@ -245,26 +300,25 @@ Pair icon size with the surrounding text scale. Pass via the `size` prop, not ra
|
|
|
245
300
|
|
|
246
301
|
**ERP target is `xl`/`2xl` desktop.** Pages should be designed for those widths first; smaller breakpoints exist for graceful degradation, not parity. Don't waste effort on mobile-first composition unless a screen explicitly calls for it. A list page that collapses gracefully at `md` is fine; a list page redesigned for `sm` is over-investment.
|
|
247
302
|
|
|
248
|
-
Two-column **behavior** (right rail stacks under
|
|
303
|
+
Two-column **behavior** (right rail stacks under `lg`): respect AppShell defaults — do not force side-by-side grids on narrow viewports. The `Layout` column width table lives in `components.md` → Layout; reuse those numbers instead of guessing rem values here.
|
|
249
304
|
|
|
250
305
|
## 5. The `astw:` prefix
|
|
251
306
|
|
|
252
|
-
AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName
|
|
307
|
+
AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName` and `className` on roots. Prefix those utilities with `astw:` so they apply to the wrapper AppShell controls.
|
|
253
308
|
|
|
254
|
-
**Do not duplicate full component trees here.** Typical patterns (full
|
|
309
|
+
**Do not duplicate full component trees here.** Typical patterns (full `DataTable` composition, `Sheet` + footer, `Table.Root` + card insets) live in `components.md` with JSX you can copy.
|
|
255
310
|
|
|
256
|
-
Minimal
|
|
311
|
+
Minimal illustration — the same rules apply to other `*ClassName` hooks:
|
|
257
312
|
|
|
258
313
|
```tsx
|
|
259
|
-
<Table.Root containerClassName="astw:px-6 astw:
|
|
260
|
-
<Sheet contentClassName="astw:w-[480px] astw:flex astw:flex-col astw:gap-4" />
|
|
314
|
+
<Table.Root containerClassName="astw:px-6 astw:overflow-y-auto" />
|
|
261
315
|
```
|
|
262
316
|
|
|
263
317
|
Rules:
|
|
264
318
|
|
|
265
|
-
-
|
|
319
|
+
- `astw:` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-background`, …) on **your** markup.
|
|
266
320
|
- Stick to **layout** utilities (`flex`, `grid`, `max-h-*`, `min-h-0`, `overflow-*`, widths). Avoid painting over internal AppShell padding or colors via `astw:` — prefer an upstream prop or composition change.
|
|
267
|
-
- Steps like
|
|
321
|
+
- Steps like `astw:p-4` still resolve through the scale — never arbitrary `astw:p-[13px]`.
|
|
268
322
|
|
|
269
323
|
## 6. When AppShell doesn't have a component you need
|
|
270
324
|
|
|
@@ -272,15 +326,15 @@ Most ERP screens compose entirely from AppShell primitives. When you hit a gap,
|
|
|
272
326
|
|
|
273
327
|
### Decision tree
|
|
274
328
|
|
|
275
|
-
1. **Can you compose existing AppShell primitives?** A "card with metric and trend arrow" is `
|
|
329
|
+
1. **Can you compose existing AppShell primitives?** A "card with a metric and a trend arrow" is `MetricCard`, or `Card` plus a lucide icon — not a new component. Compose first, and check `components.md` for what already exists before concluding there is a gap.
|
|
276
330
|
2. **If composition won't work, is the behavior one-off?** Build it locally under `src/components/<name>/` and flag it for the `build-component` skill, which promotes useful customs into AppShell upstream.
|
|
277
331
|
3. **If it's already proven reusable across 2+ apps**, skip local entirely — use the `build-component` skill to add it to AppShell directly.
|
|
278
332
|
|
|
279
333
|
### Conformance rules (non-negotiable for any custom component)
|
|
280
334
|
|
|
281
|
-
- **Tokens only.** No hex literals, no magic px values, no hand-rolled shadows. Every visual property maps to a token from Section 4.
|
|
335
|
+
- **Tokens only.** No hex literals, no magic px values, no hand-rolled shadows. Every visual property maps to a token from Section 4 — and only to a token that actually exists there.
|
|
282
336
|
- **Base UI data-attribute pattern for state.** Expose `data-*` attributes that reflect internal state; never style off React props alone. A custom toggle exposes `data-checked`; a custom step indicator exposes `data-active`, `data-completed`, etc.
|
|
283
|
-
- **Compose AppShell primitives inside.** If the custom needs a button, use `Button` — not raw `<button>`. Same for `Input`, `Badge`, `
|
|
337
|
+
- **Compose AppShell primitives inside.** If the custom needs a button, use `Button` — not raw `<button>`. Same for `Input`, `Badge`, `Card`. The custom's job is composition, not reinvention.
|
|
284
338
|
- **Document with a `README.md`** in the component folder listing: purpose, props, tokens used, and a brief justification for why this can't be composed from existing AppShell primitives.
|
|
285
339
|
- **Match accessibility behavior** of the closest AppShell equivalent — focus management, ARIA roles/attributes, keyboard interactions. Reach for Base UI primitives if the behavior is non-trivial.
|
|
286
340
|
|
|
@@ -288,7 +342,7 @@ Example skeleton for a local custom component:
|
|
|
288
342
|
|
|
289
343
|
```tsx
|
|
290
344
|
// src/components/StepIndicator/index.tsx
|
|
291
|
-
import {
|
|
345
|
+
import { Check } from "lucide-react";
|
|
292
346
|
|
|
293
347
|
type Props = { steps: string[]; current: number };
|
|
294
348
|
|
|
@@ -301,13 +355,13 @@ export function StepIndicator({ steps, current }: Props) {
|
|
|
301
355
|
data-active={i === current ? "" : undefined}
|
|
302
356
|
data-completed={i < current ? "" : undefined}
|
|
303
357
|
className="
|
|
304
|
-
flex items-center gap-2 px-3 py-2
|
|
305
|
-
bg-
|
|
306
|
-
data-[active]:bg-primary data-[active]:text-
|
|
307
|
-
data-[completed]:text-
|
|
358
|
+
flex items-center gap-2 rounded-md px-3 py-2
|
|
359
|
+
bg-muted text-sm text-muted-foreground
|
|
360
|
+
data-[active]:bg-primary data-[active]:text-primary-foreground
|
|
361
|
+
data-[completed]:text-status-completed
|
|
308
362
|
"
|
|
309
363
|
>
|
|
310
|
-
{i < current && <
|
|
364
|
+
{i < current && <Check className="size-4" />}
|
|
311
365
|
{label}
|
|
312
366
|
</li>
|
|
313
367
|
))}
|
|
@@ -316,7 +370,7 @@ export function StepIndicator({ steps, current }: Props) {
|
|
|
316
370
|
}
|
|
317
371
|
```
|
|
318
372
|
|
|
319
|
-
Notice:
|
|
373
|
+
Notice: every value is a real token, `data-*` attributes carry state, no hex literals, and the icon comes from `lucide-react` rather than a nonexistent `Icon` component.
|
|
320
374
|
|
|
321
375
|
### Promotion path
|
|
322
376
|
|
|
@@ -338,21 +392,21 @@ When a custom component proves reusable across 2+ apps, promote it upstream into
|
|
|
338
392
|
|
|
339
393
|
### Semantic decisions
|
|
340
394
|
|
|
341
|
-
| Intent | Pick
|
|
342
|
-
| ---------------------------------- |
|
|
343
|
-
| Destructive action (delete, void) |
|
|
344
|
-
| Non-blocking caution | `bg-
|
|
345
|
-
| Confirmation / completed state | `bg-
|
|
346
|
-
| Neutral callout | `
|
|
347
|
-
| Persistent panel (sidebar, header) |
|
|
348
|
-
| Hovered / sticky surface |
|
|
349
|
-
| Popover / menu / tooltip |
|
|
350
|
-
| Modal / sheet / dialog |
|
|
351
|
-
| Hover / focus transition |
|
|
352
|
-
| State change (toggle, select) |
|
|
353
|
-
| Two-column detail at <1024 | right column collapses below main — do not override
|
|
354
|
-
| Inline ID, code, table number | `text-
|
|
355
|
-
| Timestamp, label, subtle metadata | `text-
|
|
395
|
+
| Intent | Pick |
|
|
396
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
397
|
+
| Destructive action (delete, void) | `Button variant="destructive"`; `bg-destructive` on custom surfaces; confirm in a dialog at `shadow-lg` |
|
|
398
|
+
| Non-blocking caution | `Badge variant="warning"`, or `bg-status-attention` |
|
|
399
|
+
| Confirmation / completed state | `Badge variant="success"`, or `bg-status-completed` |
|
|
400
|
+
| Neutral callout | `Badge variant="info"`, or the `Alert` component |
|
|
401
|
+
| Persistent panel (sidebar, header) | `shadow-sm` |
|
|
402
|
+
| Hovered / sticky surface | `shadow-md` |
|
|
403
|
+
| Popover / menu / tooltip | `bg-popover`, `shadow-md`, `duration-150` |
|
|
404
|
+
| Modal / sheet / dialog | `shadow-lg`, `duration-300` entrance |
|
|
405
|
+
| Hover / focus transition | `duration-150 ease-out` |
|
|
406
|
+
| State change (toggle, select) | `duration-200 ease-in-out` |
|
|
407
|
+
| Two-column detail at <1024 | right column collapses below main — do not override |
|
|
408
|
+
| Inline ID, code, table number | `font-mono text-xs` (identifiers) / `tabular-nums` (figures) |
|
|
409
|
+
| Timestamp, label, subtle metadata | `text-xs text-muted-foreground` |
|
|
356
410
|
|
|
357
411
|
### Composition & emphasis rules
|
|
358
412
|
|
|
@@ -366,9 +420,9 @@ These are visual-composition rules every screen must follow, regardless of patte
|
|
|
366
420
|
- **Secondary statuses** (delivery, billing, fulfilment) and dense supporting columns → **`outline-*`** (with status dot).
|
|
367
421
|
- **Tags / labels** ("New", "Returned") → **`subtle-*`**.
|
|
368
422
|
- Reserve **`default`** (brand fill) for non-status emphasis — never the brand color as a routine status. The defect to avoid: making _every_ chip a loud fill, or giving secondary statuses the same weight as the primary one. (Variants: **`components.md`** → `Badge`.)
|
|
369
|
-
- **Color:** status colors
|
|
423
|
+
- **Color:** status colors signal meaning, not decoration — don't tint neutral content.
|
|
370
424
|
|
|
371
|
-
**Hierarchy.** One `h1` per page (the `Layout.Header` title). Section headings step down
|
|
425
|
+
**Hierarchy.** One `h1` per page (the `Layout.Header` title). Section headings step down in weight and size; never skip levels for size — pick the role from §4 Typography, not the pixel size.
|
|
372
426
|
|
|
373
427
|
**States — never ship only the happy path.** Every data-backed screen handles:
|
|
374
428
|
|