@inbeat/standards 0.17.0 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.18.1](https://github.com/Genoux/ib-toolkit/compare/standards-v0.18.0...standards-v0.18.1) (2026-11-18)
4
+
5
+
6
+ ### Miscellaneous Chores
7
+
8
+ * **standards:** Synchronize inbeat versions
9
+
10
+ ## [0.18.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.17.0...standards-v0.18.0) (2026-11-18)
11
+
12
+
13
+ ### Features
14
+
15
+ * 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))
16
+
17
+
18
+ ### Bug Fixes
19
+
20
+ * **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))
21
+ * **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))
22
+
3
23
  ## [0.17.0](https://github.com/Genoux/ib-toolkit/compare/standards-v0.16.0...standards-v0.17.0) (2026-11-17)
4
24
 
5
25
 
@@ -4,6 +4,10 @@
4
4
 
5
5
  -
6
6
 
7
+ ### Look
8
+
9
+ -
10
+
7
11
  ### Stack deltas
8
12
 
9
13
  -
@@ -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
- - UI comes only from `@inbeat/ui` (catalog in the `ib-ui` skill) plus layouts composed from it. If a
90
- component or variant is missing, stop and flag it for ib-toolkit; never invent, copy or patch
91
- one (a workaround needs the user's OK and a `// toolkit-gap:` comment).
92
- - Primitives and generic blocks from `@inbeat/ui/components/*`; tokens from
93
- `@inbeat/ui/theme.css`, plus the opt-in Fieldtrip brand layer `@inbeat/ui/fieldtrip.css` (see
94
- "Look" in the `ib-ui` skill). A block moves to the toolkit only once an app actually uses it.
95
- - Buttons are `rounded-full` with no destructive variant; destructive flows use
96
- `DestructiveActionDialog` from `@inbeat/ui`. Icon-only buttons get a tooltip. Lists use
97
- `DataTableShell` + `DataTable`; empty lists use `EmptyState`.
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.17.0",
3
+ "version": "0.18.1",
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.17.0",
35
+ "@inbeat/config": "^0.18.1",
36
36
  "vitest": "^4.1.1"
37
37
  },
38
38
  "repository": {
@@ -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
- Check the [Catalog](#catalog). Build pages and domain compositions only from catalog components
11
- and tokens. Icons are always `lucide-react`.
12
-
13
- **Allowed in the app**: page layouts and domain compositions (a `CreatorCard` from `Avatar` +
14
- `Badge`) in `src/shared/components/blocks` or the feature's `components/`. Different apps may
15
- compose different layouts.
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`. The components are the
160
- same in all three; only tokens and app-owned components change.
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 (`--primary`, `--radius`, ...) in the app's `globals.css`
170
- after the imports, and build components only that product needs (a game card, a custom
171
- dropdown) in the app, on the same tokens. They are not toolkit gaps and stay in the app until a
172
- second app needs them. Never copy a toolkit component into the app to edit it.
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 { typeScaleProblems } from "./type-scale";
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 offScale = typeScaleProblems(appDir);
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 (offScale.length > 0) {
81
+ if (offRules.length > 0) {
82
82
  console.error(
83
- 'outside the type scale (see "UI" in the standard; pick a role, or change the scale in ' +
84
- `ib-toolkit):\n ${offScale.join("\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 + offScale.length === 0 ? 0 : 1;
87
+ return stale.length + ignoring.length + problems.length + offRules.length === 0 ? 0 : 1;
88
88
  },
89
89
  mcp: () =>
90
90
  runMcp(args, {
@@ -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
  }
@@ -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
- Check the [Catalog](#catalog). Build pages and domain compositions only from catalog components
11
- and tokens. Icons are always `lucide-react`.
12
-
13
- **Allowed in the app**: page layouts and domain compositions (a `CreatorCard` from `Avatar` +
14
- `Badge`) in `src/shared/components/blocks` or the feature's `components/`. Different apps may
15
- compose different layouts.
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`. The components are the
160
- same in all three; only tokens and app-owned components change.
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 (`--primary`, `--radius`, ...) in the app's `globals.css`
170
- after the imports, and build components only that product needs (a game card, a custom
171
- dropdown) in the app, on the same tokens. They are not toolkit gaps and stay in the app until a
172
- second app needs them. Never copy a toolkit component into the app to edit it.
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
 
@@ -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
- - UI comes only from `@inbeat/ui` (catalog in the `ib-ui` skill) plus layouts composed from it. If a
93
- component or variant is missing, stop and flag it for ib-toolkit; never invent, copy or patch
94
- one (a workaround needs the user's OK and a `// toolkit-gap:` comment).
95
- - Primitives and generic blocks from `@inbeat/ui/components/*`; tokens from
96
- `@inbeat/ui/theme.css`, plus the opt-in Fieldtrip brand layer `@inbeat/ui/fieldtrip.css` (see
97
- "Look" in the `ib-ui` skill). A block moves to the toolkit only once an app actually uses it.
98
- - Buttons are `rounded-full` with no destructive variant; destructive flows use
99
- `DestructiveActionDialog` from `@inbeat/ui`. Icon-only buttons get a tooltip. Lists use
100
- `DataTableShell` + `DataTable`; empty lists use `EmptyState`.
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.
@@ -0,0 +1,4 @@
1
+ {
2
+ "$schema": "https://docs.renovatebot.com/renovate-schema.json",
3
+ "extends": ["github>Genoux/ib-toolkit//renovate.json5"]
4
+ }
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
- }