@inbeat/standards 0.17.0 → 0.18.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/CHANGELOG.md +13 -0
- package/agents/app-section.md +4 -0
- package/agents/standard.md +17 -10
- package/package.json +2 -2
- package/skills/ib-ui/SKILL.md +67 -13
- package/src/cli.ts +6 -6
- package/src/external-skills.ts +4 -0
- package/src/ui-rules.ts +59 -0
- package/template/.agents/skills/ib-ui/SKILL.md +67 -13
- package/template/AGENTS.md +25 -10
- package/template/renovate.json +4 -0
- package/src/type-scale.ts +0 -41
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.18.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.17.0...standards-v0.18.0) (2026-11-18)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* page layout, look layers and ui rules in ib check ([#81](https://github.com/Genoux/ib-toolkit/issues/81)) ([0bb464e](https://github.com/Genoux/ib-toolkit/commit/0bb464e262595d75c37ea4b39af6306599571ebc))
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
* **standards:** keep downloaded skills out of the app's lint ([#85](https://github.com/Genoux/ib-toolkit/issues/85)) ([a4e42e4](https://github.com/Genoux/ib-toolkit/commit/a4e42e4223f4543595fd26113c6aa78b06b3cce7))
|
|
14
|
+
* **ui:** show a record's key facts as one card each ([#83](https://github.com/Genoux/ib-toolkit/issues/83)) ([b7b02c1](https://github.com/Genoux/ib-toolkit/commit/b7b02c177c1a8bf495748304b1b7ded0153a3d11))
|
|
15
|
+
|
|
3
16
|
## [0.17.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.16.0...standards-v0.17.0) (2026-11-17)
|
|
4
17
|
|
|
5
18
|
|
package/agents/app-section.md
CHANGED
package/agents/standard.md
CHANGED
|
@@ -8,6 +8,8 @@ file into the app; change it in ib-toolkit.
|
|
|
8
8
|
|
|
9
9
|
- If "Product brief" under "This app" is empty, write the user's brief there first (problem,
|
|
10
10
|
users, core flows), then build.
|
|
11
|
+
- Before any UI, "Look" under "This app" names one of neutral, Fieldtrip or product-specific
|
|
12
|
+
(see "Look" in the `ib-ui` skill). If the heading is missing or empty, ask the user, then add it.
|
|
11
13
|
- Read the matching guide before the work, whatever tool you are: `.agents/skills/ib-ui/SKILL.md`
|
|
12
14
|
(component catalog, UI rules) before any UI, `.agents/skills/ib-feature/SKILL.md` for a new
|
|
13
15
|
feature, `.agents/skills/ib-toolkit/SKILL.md` for actions, routes, auth, env and rate limits.
|
|
@@ -86,15 +88,21 @@ Server actions are queued per client; never use them for reads.
|
|
|
86
88
|
|
|
87
89
|
### UI
|
|
88
90
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
91
|
+
Every app shares one foundation and is free to derive its own product on top of it. Each piece of
|
|
92
|
+
UI is in exactly one of three layers:
|
|
93
|
+
|
|
94
|
+
| Layer | What | Rule |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| Plumbing | buttons, inputs, forms, dialogs, menus, tables, toasts, tabs, the app shell, page frame, type scale, spacing | Only from `@inbeat/ui`. Missing piece: stop and flag it for ib-toolkit; never invent, copy or patch one (a workaround needs the user's OK and a `// toolkit-gap:` comment). |
|
|
97
|
+
| Look | colours, fonts, radius, shadows | Tokens only, chosen under "Look": neutral `theme.css`, the Fieldtrip layer, or the app's own token overrides in `globals.css`. Never hex or one-off values in components. |
|
|
98
|
+
| Signature surfaces | what makes this product itself: a game board, a canvas, a hero, a custom card or player | Free, built in the app on the tokens and plumbing. They stay in the app until a second app needs them. |
|
|
99
|
+
|
|
100
|
+
- Pages follow the page patterns in the `ib-ui` skill (list, detail, form, overview). A page that
|
|
101
|
+
needs a different layout is allowed; record it under **Deliberate deviations**.
|
|
102
|
+
- Design and taste skills (`frontend-design`, `taste-skill`, `emil-design-eng`,
|
|
103
|
+
`make-interfaces-feel-better`, `stageshow` and the like) apply to signature surfaces and to a
|
|
104
|
+
product-specific look only. For plumbing and page layout, `ib-ui` wins over any skill that asks
|
|
105
|
+
for a distinctive or bolder look.
|
|
98
106
|
- Type scale: every text takes one of these roles and nothing sets a size or weight of its own
|
|
99
107
|
(`ib check` fails on `text-[13px]`, `font-[510]`, `font-bold`). Body `text-sm` (14px): inputs,
|
|
100
108
|
menu items, detail values, person names. Table cells are 13.5px, set by `Table`, and column
|
|
@@ -105,7 +113,6 @@ Server actions are queued per client; never use them for reads.
|
|
|
105
113
|
`text-xl font-semibold`. Secondary information is `text-muted-foreground`, never smaller.
|
|
106
114
|
Weights are regular, medium and semibold. Larger named sizes are for display text on public
|
|
107
115
|
and onboarding screens. To change the scale, change it in ib-toolkit.
|
|
108
|
-
- People in a table are avatars only (`MemberAvatarStack`); it names them in a tooltip.
|
|
109
116
|
- Radix via `radix-ui`; animation via `motion` only.
|
|
110
117
|
|
|
111
118
|
### Simplicity
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@inbeat/standards",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.18.0",
|
|
4
4
|
"description": "Agent standards for inBeat apps: managed AGENTS.md block, skills under .agents/skills, shared third-party skills, ib CLI",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"test": "bun --bun vitest run"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
|
-
"@inbeat/config": "^0.
|
|
35
|
+
"@inbeat/config": "^0.18.0",
|
|
36
36
|
"vitest": "^4.1.1"
|
|
37
37
|
},
|
|
38
38
|
"repository": {
|
package/skills/ib-ui/SKILL.md
CHANGED
|
@@ -7,16 +7,24 @@ description: Build UI in an inBeat app with @inbeat/ui primitives and tokens. Us
|
|
|
7
7
|
|
|
8
8
|
## Before writing any UI
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
1. Read "Look" under "This app" in `AGENTS.md`. If it is empty, settle it with the user first
|
|
11
|
+
(see [Look](#look-neutral-fieldtrip-or-product-specific)).
|
|
12
|
+
2. Name the layer of what you are about to build (the table is in the "UI" section of the
|
|
13
|
+
standard):
|
|
14
|
+
- **Plumbing** (controls, forms, dialogs, menus, tables, tabs, toasts, shell, page frame):
|
|
15
|
+
only from the [Catalog](#catalog), laid out with a [page pattern](#page-patterns).
|
|
16
|
+
- **Signature surface** (what makes this product itself: a game board, a canvas, a hero, a
|
|
17
|
+
custom card): build it in the feature's `components/` on the tokens, with catalog pieces
|
|
18
|
+
inside it where they fit. Design and taste skills are welcome here.
|
|
19
|
+
3. Pick the page pattern. A page that needs another layout is fine; add a line under
|
|
20
|
+
**Deliberate deviations** saying which page and why.
|
|
21
|
+
|
|
22
|
+
Icons are always `lucide-react`.
|
|
16
23
|
|
|
17
24
|
**Not allowed**: new generic primitives or variants (a local button, modal, select, table or
|
|
18
25
|
toast), copying or restyling a toolkit component, faking a variant with override classes,
|
|
19
|
-
installing another UI library, running `shadcn add`.
|
|
26
|
+
installing another UI library, running `shadcn add`. `ib check` fails on other UI, icon and
|
|
27
|
+
animation libraries, hand-set colours, spacing lengths and type sizes.
|
|
20
28
|
|
|
21
29
|
**Missing component**: stop. Tell the user which component or variant is missing and why, and
|
|
22
30
|
propose adding it to ib-toolkit (`packages/ui` plus its story). Only with the user's explicit
|
|
@@ -53,6 +61,7 @@ agreement, use a workaround and mark it `// toolkit-gap: <what is missing>` so i
|
|
|
53
61
|
toggles: `label="Show filters" pressedLabel="Hide filters" pressed={isOpen}`; `pressed` owns the
|
|
54
62
|
look. Menu and popover triggers are not toggles: static label, no `pressed`.
|
|
55
63
|
- Labels are one to three words, no ids or emails.
|
|
64
|
+
- People in a table are avatars only (`MemberAvatarStack`); it names them in a tooltip.
|
|
56
65
|
- Lists: `DataTableShell` + `DataTable`. With no data render `EmptyState` instead of the table;
|
|
57
66
|
DataTable's "No results." is only for an empty filter result.
|
|
58
67
|
- Forms (client leaf): `schema.safeParse(values)` with the schema shared with the action; on
|
|
@@ -65,6 +74,32 @@ agreement, use a workaround and mark it `// toolkit-gap: <what is missing>` so i
|
|
|
65
74
|
- `page.tsx` stays a Server Component (title, layout, data loading); only the stateful leaf (a
|
|
66
75
|
table with dialogs, a form) is `"use client"`.
|
|
67
76
|
|
|
77
|
+
## Page patterns
|
|
78
|
+
|
|
79
|
+
Every page body is `Page` > `PageHeader` > content. Stories: Storybook "Layout/Page". These are
|
|
80
|
+
the default; a page that needs something else is recorded under **Deliberate deviations**.
|
|
81
|
+
|
|
82
|
+
- **Frame.** Inside `AppShell`, the shell header holds the `Breadcrumb` (where you are) and the
|
|
83
|
+
page body starts with `PageHeader` (what this page is, its actions). A top-level page with no
|
|
84
|
+
trail leaves the shell header empty. Actions sit in `PageHeader actions`: at most one primary
|
|
85
|
+
`Button`, the rest `secondary`, `IconButton` or a `dots` menu.
|
|
86
|
+
- **List**: `Page` > `PageHeader` (title, description, the create action) > `PageSection` with the
|
|
87
|
+
filter bar (`SearchInput`, `TabsList` or `TogglePills`) above `DataTableShell` + `DataTable`.
|
|
88
|
+
No data at all: `EmptyState` replaces the section, its action the same as the header's. Use
|
|
89
|
+
`size="full"` when the table needs the width.
|
|
90
|
+
- **Detail**: `Page` > `PageHeader` (the record's name, a one-line summary, edit and `dots`
|
|
91
|
+
actions) > optional `Tabs` > one `PageSection` per group: key facts as a grid of
|
|
92
|
+
`Card`s, one `LabeledField` each (`grid gap-4 sm:grid-cols-3`, the same grid as overview
|
|
93
|
+
stats), related lists as tables.
|
|
94
|
+
- **Form and settings**: `Page size="narrow"` > `PageHeader` > one `PageSection` per topic, each
|
|
95
|
+
holding a `Card` with a `FieldGroup`; the save `Button` ends its card. Destructive settings go in
|
|
96
|
+
a last section and open `DestructiveActionDialog`.
|
|
97
|
+
- **Overview**: `Page` > `PageHeader` > a grid of stat `Card`s (`grid gap-4 sm:grid-cols-3`) >
|
|
98
|
+
`PageSection`s for what needs attention.
|
|
99
|
+
- **Spacing** comes from these components: `Page` spaces its children with `gap-8`, sections use
|
|
100
|
+
`gap-4`, cards `p-5 gap-4`. Add spacing only inside your own compositions, one gap step per
|
|
101
|
+
level.
|
|
102
|
+
|
|
68
103
|
## Catalog
|
|
69
104
|
|
|
70
105
|
Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
@@ -96,6 +131,7 @@ Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
|
96
131
|
- `components/number-dot`: small count pill, renders nothing at zero.
|
|
97
132
|
- `components/labeled-field`: read-only label and value pair.
|
|
98
133
|
- `components/empty-state`: EmptyState with icon, title, description and an optional labelled action: `onClick`, or `href` so a Server Component can link (pass `renderLink` for the router Link; it must forward props and ref, which `next/link` does).
|
|
134
|
+
- `components/card`: Card, the bordered surface for a group of content (a form, key facts, a stat); padding and gap built in.
|
|
99
135
|
- `components/separator`: horizontal or vertical Separator.
|
|
100
136
|
- `components/carousel`: Embla Carousel, CarouselContent and CarouselItem.
|
|
101
137
|
- `components/collapsible-section`: animated CollapsibleSection with trigger and content.
|
|
@@ -134,6 +170,7 @@ Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
|
134
170
|
|
|
135
171
|
### Layout
|
|
136
172
|
- `components/app-shell`: AppShell page frame with sidebar and header, and AppShellLogo.
|
|
173
|
+
- `components/page`: Page (centred body column; `size` default, narrow or full), PageHeader (`title`, `description`, `actions`) and PageSection (optional `title`, `description`, `actions`, then content).
|
|
137
174
|
|
|
138
175
|
### Hooks and lib
|
|
139
176
|
- `hooks/use-mobile`: `useIsMobile()` breakpoint hook.
|
|
@@ -156,8 +193,10 @@ The template installs every peer the catalog needs.
|
|
|
156
193
|
|
|
157
194
|
## Look: neutral, Fieldtrip, or product-specific
|
|
158
195
|
|
|
159
|
-
Decide this when the app starts and record it in the app's `AGENTS.md
|
|
160
|
-
|
|
196
|
+
Decide this when the app starts and record it under "Look" in the app's `AGENTS.md`, one line:
|
|
197
|
+
the choice plus, for product-specific, which tokens it overrides and why (`product-specific:
|
|
198
|
+
--primary, --radius and font-sans for a playful game feel`). The components are the same in all
|
|
199
|
+
three; only tokens and signature surfaces change.
|
|
161
200
|
|
|
162
201
|
- **Neutral** (default; dashboards and internal tools): `theme.css` alone.
|
|
163
202
|
- **Fieldtrip brand**: add `@import "@inbeat/ui/fieldtrip.css";` after `theme.css`. It gives the
|
|
@@ -166,10 +205,25 @@ same in all three; only tokens and app-owned components change.
|
|
|
166
205
|
`font-sans` to SwissNow and `font-serif` to Diplomat. The font files are licensed and stay in
|
|
167
206
|
the app: load them with `next/font/local` and put `--font-swiss-now` and `--font-diplomat` on
|
|
168
207
|
`<html>`.
|
|
169
|
-
- **Product-specific**: override tokens
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
208
|
+
- **Product-specific**: override tokens in the app's `globals.css` after the imports: colours and
|
|
209
|
+
`--radius` in `:root` (and `.dark`), fonts as `--font-sans` in `@theme inline`, the way
|
|
210
|
+
`fieldtrip.css` does. Every toolkit component follows, so the plumbing takes
|
|
211
|
+
the product's look without a single override class. Colours the product adds get their own
|
|
212
|
+
tokens there (`--color-board: ...` in `@theme`), never hex in components. Signature surfaces
|
|
213
|
+
(a game card, a player) are built in the app on these tokens; they are not toolkit gaps and stay
|
|
214
|
+
in the app until a second app needs them. Never copy a toolkit component into the app to edit it.
|
|
215
|
+
|
|
216
|
+
## Before you say it is done
|
|
217
|
+
|
|
218
|
+
Look at what you built, the way a user will:
|
|
219
|
+
|
|
220
|
+
1. Run the app (`bun dev`) and open each page you changed at 1440px and 390px wide, in light and
|
|
221
|
+
dark when the app has both. Use your browser tool, or a Playwright screenshot.
|
|
222
|
+
2. Compare it with its [page pattern](#page-patterns) and check: content never touches a border
|
|
223
|
+
or edge; one gap step per level; one primary action per page; text takes the type roles;
|
|
224
|
+
nothing overflows or wraps a title at 390px; empty, loading and error states render.
|
|
225
|
+
3. Fix what is off before reporting. Say in the report which pages and widths you looked at; if
|
|
226
|
+
you could not run the app, say so.
|
|
173
227
|
|
|
174
228
|
## Adding or changing a component
|
|
175
229
|
|
package/src/cli.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { formatReport, installExternalSkills } from "./external-skills";
|
|
|
6
6
|
import { foundationProblems } from "./foundation";
|
|
7
7
|
import { runMcp } from "./mcp";
|
|
8
8
|
import { claudeFilesIgnoringAgents, staleFiles, write } from "./sync";
|
|
9
|
-
import {
|
|
9
|
+
import { uiRuleProblems } from "./ui-rules";
|
|
10
10
|
|
|
11
11
|
const USAGE = [
|
|
12
12
|
"usage: ib <create <dir> [--local] | sync [app-dir] | check [app-dir] | mcp>",
|
|
@@ -63,7 +63,7 @@ const commands: Record<string, () => number | Promise<number>> = {
|
|
|
63
63
|
const stale = staleFiles(appDir);
|
|
64
64
|
const ignoring = claudeFilesIgnoringAgents(appDir);
|
|
65
65
|
const problems = foundationProblems(appDir);
|
|
66
|
-
const
|
|
66
|
+
const offRules = uiRuleProblems(appDir);
|
|
67
67
|
if (stale.length > 0) {
|
|
68
68
|
console.error(
|
|
69
69
|
`out of date with @inbeat/standards, run \`ib sync\`:\n ${stale.join("\n ")}`,
|
|
@@ -78,13 +78,13 @@ const commands: Record<string, () => number | Promise<number>> = {
|
|
|
78
78
|
if (problems.length > 0) {
|
|
79
79
|
console.error(`not on the shared foundation:\n ${problems.join("\n ")}`);
|
|
80
80
|
}
|
|
81
|
-
if (
|
|
81
|
+
if (offRules.length > 0) {
|
|
82
82
|
console.error(
|
|
83
|
-
'outside the
|
|
84
|
-
`ib-toolkit):\n ${
|
|
83
|
+
'outside the UI rules (see "UI" in the standard; use the toolkit, or change it in ' +
|
|
84
|
+
`ib-toolkit):\n ${offRules.join("\n ")}`,
|
|
85
85
|
);
|
|
86
86
|
}
|
|
87
|
-
return stale.length + ignoring.length + problems.length +
|
|
87
|
+
return stale.length + ignoring.length + problems.length + offRules.length === 0 ? 0 : 1;
|
|
88
88
|
},
|
|
89
89
|
mcp: () =>
|
|
90
90
|
runMcp(args, {
|
package/src/external-skills.ts
CHANGED
|
@@ -25,6 +25,7 @@ export const SKILLS_DIR = join(".agents", "skills");
|
|
|
25
25
|
export const CLAUDE_SKILLS_DIR = join(".claude", "skills");
|
|
26
26
|
// Present in every folder this installer wrote; a folder without it is the app's own.
|
|
27
27
|
export const MARKER = ".toolkit-source";
|
|
28
|
+
const BIOME_SKIP = { root: false, files: { includes: ["!**"] } };
|
|
28
29
|
const CLAUDE_IGNORE_HEADER = "# Written by ib sync: links to the shared skills in .agents/skills.";
|
|
29
30
|
|
|
30
31
|
export type ExternalSkill = { repo: string; path: string; name?: string };
|
|
@@ -110,6 +111,9 @@ function place(skillsDir: string, source: Source, provenance: string): "installe
|
|
|
110
111
|
});
|
|
111
112
|
}
|
|
112
113
|
writeFileSync(join(dest, ".gitignore"), "*\n");
|
|
114
|
+
// Biome ignores .gitignore unless the app turns on vcs, so the app's lint would check
|
|
115
|
+
// third-party code (2751 errors in ugc-hub); a nested config that includes nothing stops it.
|
|
116
|
+
writeFileSync(join(dest, "biome.json"), `${JSON.stringify(BIOME_SKIP)}\n`);
|
|
113
117
|
writeFileSync(join(dest, MARKER), `${provenance}\n`);
|
|
114
118
|
return "installed";
|
|
115
119
|
}
|
package/src/ui-rules.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
2
|
+
import { join, relative } from "node:path";
|
|
3
|
+
|
|
4
|
+
// The plumbing and look rules of the "UI" section of the standard that a pattern can catch.
|
|
5
|
+
// Type scale: an app picks a role (text-sm, text-xs, ...) and never a size or weight of its own,
|
|
6
|
+
// so a change of scale happens once, in the toolkit. `em` sizes are relative to their parent
|
|
7
|
+
// (inline code in running text), so they follow the scale.
|
|
8
|
+
// Spacing and colour: plain lengths and colour literals are flagged; var(), env() and calc()
|
|
9
|
+
// pass, because safe-area insets, full-bleed offsets and token references need them.
|
|
10
|
+
const SPACING = "(?:space-[xy]|gap-[xy]|gap|p[xytrblse]?|m[xytrblse]?)";
|
|
11
|
+
|
|
12
|
+
const RULES = [
|
|
13
|
+
{ pattern: /\btext-\[[\d.]+(?:px|rem)\]/g, reason: "hand-set font size" },
|
|
14
|
+
{ pattern: /\bfont-\[\d+\]/g, reason: "hand-set font weight" },
|
|
15
|
+
{
|
|
16
|
+
pattern: /\bfont-(?:bold|extrabold|black)\b/g,
|
|
17
|
+
reason: "weight outside regular, medium, semibold",
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
pattern: new RegExp(`(?<![\\w-])-?${SPACING}-\\[-?[\\d.]+(?:px|rem|em)?\\]`, "g"),
|
|
21
|
+
reason: "hand-set spacing, use the spacing scale",
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
pattern:
|
|
25
|
+
/(?<![\w-])[a-z]+(?:-[a-z]+)*-\[(?:#[0-9a-fA-F]{3,8}\]|(?:rgba?|hsla?|oklch|oklab)\()/g,
|
|
26
|
+
reason: "hand-set colour, use a token",
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
pattern:
|
|
30
|
+
/from "(?:@mui\/|@chakra-ui\/|antd|@mantine\/|@headlessui\/|react-bootstrap|@nextui-org\/|@heroui\/|react-icons|@heroicons\/|@tabler\/icons|@phosphor-icons|framer-motion|@radix-ui\/)/g,
|
|
31
|
+
reason: "another UI library; use @inbeat/ui, lucide-react, radix-ui and motion",
|
|
32
|
+
},
|
|
33
|
+
];
|
|
34
|
+
|
|
35
|
+
function sourceFiles(dir: string): string[] {
|
|
36
|
+
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
37
|
+
const path = join(dir, entry.name);
|
|
38
|
+
if (entry.isDirectory()) return sourceFiles(path);
|
|
39
|
+
return /\.tsx?$/.test(entry.name) ? [path] : [];
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** `src/file.tsx:12 text-[13px] (hand-set font size)` for every match of a UI rule. */
|
|
44
|
+
export function uiRuleProblems(appDir: string): string[] {
|
|
45
|
+
const srcDir = join(appDir, "src");
|
|
46
|
+
if (!existsSync(srcDir)) return [];
|
|
47
|
+
|
|
48
|
+
return sourceFiles(srcDir).flatMap((path) =>
|
|
49
|
+
readFileSync(path, "utf8")
|
|
50
|
+
.split("\n")
|
|
51
|
+
.flatMap((line, index) =>
|
|
52
|
+
RULES.flatMap(({ pattern, reason }) =>
|
|
53
|
+
[...line.matchAll(pattern)].map(
|
|
54
|
+
([match]) => `${relative(appDir, path)}:${index + 1} ${match} (${reason})`,
|
|
55
|
+
),
|
|
56
|
+
),
|
|
57
|
+
),
|
|
58
|
+
);
|
|
59
|
+
}
|
|
@@ -7,16 +7,24 @@ description: Build UI in an inBeat app with @inbeat/ui primitives and tokens. Us
|
|
|
7
7
|
|
|
8
8
|
## Before writing any UI
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
1. Read "Look" under "This app" in `AGENTS.md`. If it is empty, settle it with the user first
|
|
11
|
+
(see [Look](#look-neutral-fieldtrip-or-product-specific)).
|
|
12
|
+
2. Name the layer of what you are about to build (the table is in the "UI" section of the
|
|
13
|
+
standard):
|
|
14
|
+
- **Plumbing** (controls, forms, dialogs, menus, tables, tabs, toasts, shell, page frame):
|
|
15
|
+
only from the [Catalog](#catalog), laid out with a [page pattern](#page-patterns).
|
|
16
|
+
- **Signature surface** (what makes this product itself: a game board, a canvas, a hero, a
|
|
17
|
+
custom card): build it in the feature's `components/` on the tokens, with catalog pieces
|
|
18
|
+
inside it where they fit. Design and taste skills are welcome here.
|
|
19
|
+
3. Pick the page pattern. A page that needs another layout is fine; add a line under
|
|
20
|
+
**Deliberate deviations** saying which page and why.
|
|
21
|
+
|
|
22
|
+
Icons are always `lucide-react`.
|
|
16
23
|
|
|
17
24
|
**Not allowed**: new generic primitives or variants (a local button, modal, select, table or
|
|
18
25
|
toast), copying or restyling a toolkit component, faking a variant with override classes,
|
|
19
|
-
installing another UI library, running `shadcn add`.
|
|
26
|
+
installing another UI library, running `shadcn add`. `ib check` fails on other UI, icon and
|
|
27
|
+
animation libraries, hand-set colours, spacing lengths and type sizes.
|
|
20
28
|
|
|
21
29
|
**Missing component**: stop. Tell the user which component or variant is missing and why, and
|
|
22
30
|
propose adding it to ib-toolkit (`packages/ui` plus its story). Only with the user's explicit
|
|
@@ -53,6 +61,7 @@ agreement, use a workaround and mark it `// toolkit-gap: <what is missing>` so i
|
|
|
53
61
|
toggles: `label="Show filters" pressedLabel="Hide filters" pressed={isOpen}`; `pressed` owns the
|
|
54
62
|
look. Menu and popover triggers are not toggles: static label, no `pressed`.
|
|
55
63
|
- Labels are one to three words, no ids or emails.
|
|
64
|
+
- People in a table are avatars only (`MemberAvatarStack`); it names them in a tooltip.
|
|
56
65
|
- Lists: `DataTableShell` + `DataTable`. With no data render `EmptyState` instead of the table;
|
|
57
66
|
DataTable's "No results." is only for an empty filter result.
|
|
58
67
|
- Forms (client leaf): `schema.safeParse(values)` with the schema shared with the action; on
|
|
@@ -65,6 +74,32 @@ agreement, use a workaround and mark it `// toolkit-gap: <what is missing>` so i
|
|
|
65
74
|
- `page.tsx` stays a Server Component (title, layout, data loading); only the stateful leaf (a
|
|
66
75
|
table with dialogs, a form) is `"use client"`.
|
|
67
76
|
|
|
77
|
+
## Page patterns
|
|
78
|
+
|
|
79
|
+
Every page body is `Page` > `PageHeader` > content. Stories: Storybook "Layout/Page". These are
|
|
80
|
+
the default; a page that needs something else is recorded under **Deliberate deviations**.
|
|
81
|
+
|
|
82
|
+
- **Frame.** Inside `AppShell`, the shell header holds the `Breadcrumb` (where you are) and the
|
|
83
|
+
page body starts with `PageHeader` (what this page is, its actions). A top-level page with no
|
|
84
|
+
trail leaves the shell header empty. Actions sit in `PageHeader actions`: at most one primary
|
|
85
|
+
`Button`, the rest `secondary`, `IconButton` or a `dots` menu.
|
|
86
|
+
- **List**: `Page` > `PageHeader` (title, description, the create action) > `PageSection` with the
|
|
87
|
+
filter bar (`SearchInput`, `TabsList` or `TogglePills`) above `DataTableShell` + `DataTable`.
|
|
88
|
+
No data at all: `EmptyState` replaces the section, its action the same as the header's. Use
|
|
89
|
+
`size="full"` when the table needs the width.
|
|
90
|
+
- **Detail**: `Page` > `PageHeader` (the record's name, a one-line summary, edit and `dots`
|
|
91
|
+
actions) > optional `Tabs` > one `PageSection` per group: key facts as a grid of
|
|
92
|
+
`Card`s, one `LabeledField` each (`grid gap-4 sm:grid-cols-3`, the same grid as overview
|
|
93
|
+
stats), related lists as tables.
|
|
94
|
+
- **Form and settings**: `Page size="narrow"` > `PageHeader` > one `PageSection` per topic, each
|
|
95
|
+
holding a `Card` with a `FieldGroup`; the save `Button` ends its card. Destructive settings go in
|
|
96
|
+
a last section and open `DestructiveActionDialog`.
|
|
97
|
+
- **Overview**: `Page` > `PageHeader` > a grid of stat `Card`s (`grid gap-4 sm:grid-cols-3`) >
|
|
98
|
+
`PageSection`s for what needs attention.
|
|
99
|
+
- **Spacing** comes from these components: `Page` spaces its children with `gap-8`, sections use
|
|
100
|
+
`gap-4`, cards `p-5 gap-4`. Add spacing only inside your own compositions, one gap step per
|
|
101
|
+
level.
|
|
102
|
+
|
|
68
103
|
## Catalog
|
|
69
104
|
|
|
70
105
|
Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
@@ -96,6 +131,7 @@ Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
|
96
131
|
- `components/number-dot`: small count pill, renders nothing at zero.
|
|
97
132
|
- `components/labeled-field`: read-only label and value pair.
|
|
98
133
|
- `components/empty-state`: EmptyState with icon, title, description and an optional labelled action: `onClick`, or `href` so a Server Component can link (pass `renderLink` for the router Link; it must forward props and ref, which `next/link` does).
|
|
134
|
+
- `components/card`: Card, the bordered surface for a group of content (a form, key facts, a stat); padding and gap built in.
|
|
99
135
|
- `components/separator`: horizontal or vertical Separator.
|
|
100
136
|
- `components/carousel`: Embla Carousel, CarouselContent and CarouselItem.
|
|
101
137
|
- `components/collapsible-section`: animated CollapsibleSection with trigger and content.
|
|
@@ -134,6 +170,7 @@ Every module of `@inbeat/ui`, imported as `@inbeat/ui/<path>`.
|
|
|
134
170
|
|
|
135
171
|
### Layout
|
|
136
172
|
- `components/app-shell`: AppShell page frame with sidebar and header, and AppShellLogo.
|
|
173
|
+
- `components/page`: Page (centred body column; `size` default, narrow or full), PageHeader (`title`, `description`, `actions`) and PageSection (optional `title`, `description`, `actions`, then content).
|
|
137
174
|
|
|
138
175
|
### Hooks and lib
|
|
139
176
|
- `hooks/use-mobile`: `useIsMobile()` breakpoint hook.
|
|
@@ -156,8 +193,10 @@ The template installs every peer the catalog needs.
|
|
|
156
193
|
|
|
157
194
|
## Look: neutral, Fieldtrip, or product-specific
|
|
158
195
|
|
|
159
|
-
Decide this when the app starts and record it in the app's `AGENTS.md
|
|
160
|
-
|
|
196
|
+
Decide this when the app starts and record it under "Look" in the app's `AGENTS.md`, one line:
|
|
197
|
+
the choice plus, for product-specific, which tokens it overrides and why (`product-specific:
|
|
198
|
+
--primary, --radius and font-sans for a playful game feel`). The components are the same in all
|
|
199
|
+
three; only tokens and signature surfaces change.
|
|
161
200
|
|
|
162
201
|
- **Neutral** (default; dashboards and internal tools): `theme.css` alone.
|
|
163
202
|
- **Fieldtrip brand**: add `@import "@inbeat/ui/fieldtrip.css";` after `theme.css`. It gives the
|
|
@@ -166,10 +205,25 @@ same in all three; only tokens and app-owned components change.
|
|
|
166
205
|
`font-sans` to SwissNow and `font-serif` to Diplomat. The font files are licensed and stay in
|
|
167
206
|
the app: load them with `next/font/local` and put `--font-swiss-now` and `--font-diplomat` on
|
|
168
207
|
`<html>`.
|
|
169
|
-
- **Product-specific**: override tokens
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
208
|
+
- **Product-specific**: override tokens in the app's `globals.css` after the imports: colours and
|
|
209
|
+
`--radius` in `:root` (and `.dark`), fonts as `--font-sans` in `@theme inline`, the way
|
|
210
|
+
`fieldtrip.css` does. Every toolkit component follows, so the plumbing takes
|
|
211
|
+
the product's look without a single override class. Colours the product adds get their own
|
|
212
|
+
tokens there (`--color-board: ...` in `@theme`), never hex in components. Signature surfaces
|
|
213
|
+
(a game card, a player) are built in the app on these tokens; they are not toolkit gaps and stay
|
|
214
|
+
in the app until a second app needs them. Never copy a toolkit component into the app to edit it.
|
|
215
|
+
|
|
216
|
+
## Before you say it is done
|
|
217
|
+
|
|
218
|
+
Look at what you built, the way a user will:
|
|
219
|
+
|
|
220
|
+
1. Run the app (`bun dev`) and open each page you changed at 1440px and 390px wide, in light and
|
|
221
|
+
dark when the app has both. Use your browser tool, or a Playwright screenshot.
|
|
222
|
+
2. Compare it with its [page pattern](#page-patterns) and check: content never touches a border
|
|
223
|
+
or edge; one gap step per level; one primary action per page; text takes the type roles;
|
|
224
|
+
nothing overflows or wraps a title at 390px; empty, loading and error states render.
|
|
225
|
+
3. Fix what is off before reporting. Say in the report which pages and widths you looked at; if
|
|
226
|
+
you could not run the app, say so.
|
|
173
227
|
|
|
174
228
|
## Adding or changing a component
|
|
175
229
|
|
package/template/AGENTS.md
CHANGED
|
@@ -11,6 +11,8 @@ file into the app; change it in ib-toolkit.
|
|
|
11
11
|
|
|
12
12
|
- If "Product brief" under "This app" is empty, write the user's brief there first (problem,
|
|
13
13
|
users, core flows), then build.
|
|
14
|
+
- Before any UI, "Look" under "This app" names one of neutral, Fieldtrip or product-specific
|
|
15
|
+
(see "Look" in the `ib-ui` skill). If the heading is missing or empty, ask the user, then add it.
|
|
14
16
|
- Read the matching guide before the work, whatever tool you are: `.agents/skills/ib-ui/SKILL.md`
|
|
15
17
|
(component catalog, UI rules) before any UI, `.agents/skills/ib-feature/SKILL.md` for a new
|
|
16
18
|
feature, `.agents/skills/ib-toolkit/SKILL.md` for actions, routes, auth, env and rate limits.
|
|
@@ -89,15 +91,21 @@ Server actions are queued per client; never use them for reads.
|
|
|
89
91
|
|
|
90
92
|
### UI
|
|
91
93
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
94
|
+
Every app shares one foundation and is free to derive its own product on top of it. Each piece of
|
|
95
|
+
UI is in exactly one of three layers:
|
|
96
|
+
|
|
97
|
+
| Layer | What | Rule |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| Plumbing | buttons, inputs, forms, dialogs, menus, tables, toasts, tabs, the app shell, page frame, type scale, spacing | Only from `@inbeat/ui`. Missing piece: stop and flag it for ib-toolkit; never invent, copy or patch one (a workaround needs the user's OK and a `// toolkit-gap:` comment). |
|
|
100
|
+
| Look | colours, fonts, radius, shadows | Tokens only, chosen under "Look": neutral `theme.css`, the Fieldtrip layer, or the app's own token overrides in `globals.css`. Never hex or one-off values in components. |
|
|
101
|
+
| Signature surfaces | what makes this product itself: a game board, a canvas, a hero, a custom card or player | Free, built in the app on the tokens and plumbing. They stay in the app until a second app needs them. |
|
|
102
|
+
|
|
103
|
+
- Pages follow the page patterns in the `ib-ui` skill (list, detail, form, overview). A page that
|
|
104
|
+
needs a different layout is allowed; record it under **Deliberate deviations**.
|
|
105
|
+
- Design and taste skills (`frontend-design`, `taste-skill`, `emil-design-eng`,
|
|
106
|
+
`make-interfaces-feel-better`, `stageshow` and the like) apply to signature surfaces and to a
|
|
107
|
+
product-specific look only. For plumbing and page layout, `ib-ui` wins over any skill that asks
|
|
108
|
+
for a distinctive or bolder look.
|
|
101
109
|
- Type scale: every text takes one of these roles and nothing sets a size or weight of its own
|
|
102
110
|
(`ib check` fails on `text-[13px]`, `font-[510]`, `font-bold`). Body `text-sm` (14px): inputs,
|
|
103
111
|
menu items, detail values, person names. Table cells are 13.5px, set by `Table`, and column
|
|
@@ -108,7 +116,6 @@ Server actions are queued per client; never use them for reads.
|
|
|
108
116
|
`text-xl font-semibold`. Secondary information is `text-muted-foreground`, never smaller.
|
|
109
117
|
Weights are regular, medium and semibold. Larger named sizes are for display text on public
|
|
110
118
|
and onboarding screens. To change the scale, change it in ib-toolkit.
|
|
111
|
-
- People in a table are avatars only (`MemberAvatarStack`); it names them in a tooltip.
|
|
112
119
|
- Radix via `radix-ui`; animation via `motion` only.
|
|
113
120
|
|
|
114
121
|
### Simplicity
|
|
@@ -132,6 +139,14 @@ Never commit, push or open a PR unless explicitly asked.
|
|
|
132
139
|
|
|
133
140
|
## This app
|
|
134
141
|
|
|
142
|
+
### Product brief
|
|
143
|
+
|
|
144
|
+
-
|
|
145
|
+
|
|
146
|
+
### Look
|
|
147
|
+
|
|
148
|
+
-
|
|
149
|
+
|
|
135
150
|
### Stack deltas
|
|
136
151
|
|
|
137
152
|
- No authentication by default; see "Integrations" in the `ib-toolkit` skill.
|
package/src/type-scale.ts
DELETED
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
import { existsSync, readdirSync, readFileSync } from "node:fs";
|
|
2
|
-
import { join, relative } from "node:path";
|
|
3
|
-
|
|
4
|
-
// The type scale lives in @inbeat/ui and in the "UI" section of the standard. An app picks a
|
|
5
|
-
// role (text-sm, text-xs, text-base, ...) and never a size or weight of its own, so a change of
|
|
6
|
-
// scale happens once, in the toolkit.
|
|
7
|
-
// `em` sizes are relative to their parent (inline code in running text), so they follow the scale.
|
|
8
|
-
const OFF_SCALE = [
|
|
9
|
-
{ pattern: /\btext-\[[\d.]+(?:px|rem)\]/g, reason: "hand-set font size" },
|
|
10
|
-
{ pattern: /\bfont-\[\d+\]/g, reason: "hand-set font weight" },
|
|
11
|
-
{
|
|
12
|
-
pattern: /\bfont-(?:bold|extrabold|black)\b/g,
|
|
13
|
-
reason: "weight outside regular, medium, semibold",
|
|
14
|
-
},
|
|
15
|
-
];
|
|
16
|
-
|
|
17
|
-
function sourceFiles(dir: string): string[] {
|
|
18
|
-
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
19
|
-
const path = join(dir, entry.name);
|
|
20
|
-
if (entry.isDirectory()) return sourceFiles(path);
|
|
21
|
-
return entry.name.endsWith(".tsx") ? [path] : [];
|
|
22
|
-
});
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
/** `src/file.tsx:12 text-[13px] (hand-set font size)` for every class outside the type scale. */
|
|
26
|
-
export function typeScaleProblems(appDir: string): string[] {
|
|
27
|
-
const srcDir = join(appDir, "src");
|
|
28
|
-
if (!existsSync(srcDir)) return [];
|
|
29
|
-
|
|
30
|
-
return sourceFiles(srcDir).flatMap((path) =>
|
|
31
|
-
readFileSync(path, "utf8")
|
|
32
|
-
.split("\n")
|
|
33
|
-
.flatMap((line, index) =>
|
|
34
|
-
OFF_SCALE.flatMap(({ pattern, reason }) =>
|
|
35
|
-
[...line.matchAll(pattern)].map(
|
|
36
|
-
([className]) => `${relative(appDir, path)}:${index + 1} ${className} (${reason})`,
|
|
37
|
-
),
|
|
38
|
-
),
|
|
39
|
-
),
|
|
40
|
-
);
|
|
41
|
-
}
|