@eigenhq/kern 0.1.0 → 0.1.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@eigenhq/kern",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "A design system for products with agents in them: components, primitives, motion and a theme contract.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -13,15 +13,19 @@
13
13
  "import": "./dist/index.js"
14
14
  },
15
15
  "./styles.css": "./src/styles/kern.css",
16
- "./themes/eigen.css": "./themes/eigen.css"
16
+ "./themes/eigen.css": "./themes/eigen.css",
17
+ "./recipes/*": "./skills/kern/recipes/*.tsx"
17
18
  },
18
19
  "files": [
19
20
  "dist",
21
+ "dist-artifact",
20
22
  "src/styles",
23
+ "src/code/code.css",
21
24
  "themes",
22
25
  "LICENSE",
23
26
  "THIRD_PARTY_NOTICES.md",
24
- "NOTICE"
27
+ "NOTICE",
28
+ "skills"
25
29
  ],
26
30
  "scripts": {
27
31
  "build": "tsup",
@@ -29,7 +33,10 @@
29
33
  "lint": "eslint src",
30
34
  "test": "vitest run",
31
35
  "catalog": "tsx catalog/build-checklist.ts",
32
- "checks:lower": "tsx checks/lower-baseline.ts"
36
+ "checks:lower": "tsx checks/lower-baseline.ts",
37
+ "build:artifact": "node scripts/build-artifact.mjs",
38
+ "prepublishOnly": "npm run build && npm run build:artifact",
39
+ "build:ds": "npm run build && npm run build:artifact && node scripts/build-ds.mjs"
33
40
  },
34
41
  "dependencies": {
35
42
  "@eigenhq/zeichen": "^0.1.0",
@@ -0,0 +1,119 @@
1
+ ---
2
+ name: kern
3
+ description: How to build screens, pages and artifacts with Kern (@eigenhq/kern, eigen.design), Eigen's design system for products with agents in them. Use whenever you build or review UI with Kern — an app screen, a dashboard, a settings page, a document, an agent run or eval review, a Claude artifact — or when a request mentions Kern, eigen.design or @eigenhq/kern. It says which part to use for what, the spacing and widths to hold, and how to load Kern where there is no npm.
4
+ ---
5
+
6
+ # Building with Kern
7
+
8
+ Kern is a set of React parts, tokens and motion for products with agents in them. Every screen should be **assembled
9
+ from Kern's parts**, not redrawn with your own `div`s and Tailwind colours. Most bad Kern screens come from the same
10
+ four mistakes, so check for them first:
11
+
12
+ 1. **Everything drawn as a chat bubble.** A bubble is only for something a person or the agent *said*. What the system
13
+ did is an event line; a tool call is a tool call; a link is a link preview; a result is a card or a row.
14
+ 2. **No padding, no measure.** Content runs edge to edge and text runs the full width of a wide pane. Panes have fixed
15
+ insets and text has a reading width.
16
+ 3. **Cards inside cards, and cards for prose.** A card holds controls or tappable rows. Prose sits on the page.
17
+ 4. **Nothing to dig into.** A list of results with no inspector. Anything with detail (a run, a person, a message)
18
+ opens an inspector with tabs.
19
+
20
+ ## Set up
21
+
22
+ ```bash
23
+ npm install @eigenhq/kern # restricted to the eigenhq org: needs an npm login or NPM_TOKEN with read access
24
+ ```
25
+
26
+ ```css
27
+ @import "tailwindcss";
28
+ @import "@eigenhq/kern/styles.css";
29
+ @import "@eigenhq/kern/themes/eigen.css";
30
+ @source "../node_modules/@eigenhq/kern/dist"; /* so Tailwind keeps the classes Kern's parts use */
31
+ ```
32
+
33
+ - Put the `kern` class on the app root (system font, Kern's base). Dark mode is a `dark` class on any ancestor; `light`
34
+ scopes a subtree back to light.
35
+ - Wrap the app in `TooltipProvider`, and in `UiProvider` with your router's link component if you route.
36
+ - Icons come from Kern's exports (`ChatRoundIcon`, `CheckCircleIcon`, …), which are Zeichen's. Follow the Zeichen skill
37
+ for choosing glyphs.
38
+ - **In a Claude artifact or any page without npm**, read `references/artifacts.md`: inline Kern's artifact build
39
+ (`dist-artifact/kern-artifact.js` and `.css`) and mount with `Kern.mount`.
40
+
41
+ ## The rules that matter
42
+
43
+ Full detail, with the exact tokens and classes, is in `references/rules.md`.
44
+
45
+ - **Panes line up.** A pane's top row sits 12px down (`pt-pane-top`) with 36px controls (`h-control`). Content inside a
46
+ pane has 16px at the sides (`px-4`); an inspector's content uses `Page` (12px sides, 32px between sections).
47
+ - **Sections are 32px apart** (`gap-section`), separated by space, not borders. Hairlines only between rows of one list.
48
+ - **Text has a measure.** Body text at most about 62 characters (`max-w-[62ch]`, `BodyText measure`, `Lead`). Bubbles
49
+ never span a pane: use `ThreadedTranscript` (it sizes them), or cap a lone bubble at about 70% of the column.
50
+ - **Type by role**, never by pixel: `text-caption` 11, `text-footnote` 12, `text-body` 13, `text-callout` 15,
51
+ `text-headline` 17, `text-title` 22, `text-large-title` 26. One semibold element per row at most.
52
+ - **Colour by token.** Surfaces `bg-surface-base` / `-grouped` / `-sidebar`, text `text-label-primary` / `-secondary` /
53
+ `-tertiary`, the one accent `tint-base`, state through `StatusPill`, `Badge` or `Alert`. Decorative colour is one of
54
+ the seven palette ramps — `meadow`, `air`, `cloud`, `poplar`, `path`, `dusk`, `roof` (`bg-poplar-500`). Never a hex
55
+ value, never a default Tailwind colour (`bg-blue-500`).
56
+ - **Glass is for what floats.** Cards (`Card`, `PageSection variant="card"`) and capsules are glass over the wash; never
57
+ a solid or coloured card, never a card in a card.
58
+ - **Words.** Sentence case everywhere. No eyebrow over a heading, no letter-spaced capitals. Pills are lowercase state
59
+ words (`met`, `missed`, `review`). A button says what happens. An empty state is one sentence. Tooltips explain
60
+ something not obvious, never just repeat a button's name.
61
+ - **Motion** comes with the parts; don't add your own. Everything has a reduced-motion form.
62
+
63
+ ## Pick the part
64
+
65
+ The full table is `references/choosing-parts.md`. The ones that matter most:
66
+
67
+ | You want to show | Use |
68
+ | --- | --- |
69
+ | What a person or agent said | `ChatBubble` inside `ThreadedTranscript` inside `ConversationView` |
70
+ | Something the system did (a run finished, a trigger, a handoff) | `TranscriptEventDivider`, `HandoffDivider`, `AgentChangeDivider` |
71
+ | Tool calls | `ToolCallGroup` / `ToolCallCard` (inputs, result, error, duration) |
72
+ | A link someone sent | `LinkPreviewCard` |
73
+ | How a run went, step by step | `RunTimeline` (`stroke` under a reply, `waterfall` or `list` in an inspector) |
74
+ | Raw logs | `LogStream` |
75
+ | A JSON payload | `JsonViewer` |
76
+ | A state word | `StatusPill` (lowercase) or `Badge` |
77
+ | Comparing two versions | `SegmentedControl` in the pane's `PaneBar` |
78
+ | A list to pick from | `ListPane` + `ListRows` + `ListRow` |
79
+ | Details of the picked thing | `InspectorPane` + `PageTabBar` + `SegmentedControl` tabs + `Page` + `PageSection` |
80
+ | Facts (id, model, cost) | `HairlineList` + `FactRow`, ids with `CopyableValue` |
81
+ | Settings rows | `PageSection variant="card"` + `InsetRow` with `Switch` / `TrailingValue` |
82
+ | Numbers over time | `ChartContainer` + `BarChart` / `LineChart`, `Sparkline` in a stat |
83
+ | An answer with sources | `CitedAnswer`, `SourcesPanel` |
84
+ | Asking the person | `ApprovalRequest`, `QuestionCard` |
85
+
86
+ **Reviewing agent runs or evals** (a run, a transcript, a rubric, a judge) has its own guide:
87
+ `references/agent-runs.md`. Read it before building any run viewer.
88
+
89
+ ## Recipes
90
+
91
+ Complete, typed, copy-pasteable screens built only from Kern's exports, in `recipes/` and as
92
+ `@eigenhq/kern/recipes/<name>`. Each is drawn live on eigen.design at `/recipes/<name>`.
93
+
94
+ | Recipe | What it shows |
95
+ | --- | --- |
96
+ | `run-review.tsx` | An agent run against a rubric: runs list, conversation with events, tool calls and link previews, before/after switch in the pane bar, inspector with Rubric, Trace and Judge tabs |
97
+ | `app-shell.tsx` | The three panes: list with search, content with a large title, inspector with tabs |
98
+ | `settings-page.tsx` | Fields with descriptions, switches in a card of rows, actions at the end |
99
+ | `dashboard.tsx` | Stat cards with sparklines, charts in cards, then a table with status pills |
100
+ | `document.tsx` | A report read top to bottom: measure, headings, callout, quote, code |
101
+
102
+ Start from the closest recipe rather than from an empty file.
103
+
104
+ ## References
105
+
106
+ - `references/rules.md` — spacing, widths, type, colour, surfaces, icons, words and motion, each with its class or part.
107
+ - `references/choosing-parts.md` — the whole catalogue as "you want X → use Y".
108
+ - `references/props.md` — the props of the parts you reach for most; the full reference is `dist/index.d.ts`.
109
+ - `references/agent-runs.md` — run viewers, eval and rubric reviews, traces and judges.
110
+ - `references/artifacts.md` — Kern in a Claude artifact or any page without npm.
111
+
112
+ ## Before you finish
113
+
114
+ - [ ] Every pane and page has its insets; nothing touches a pane's edge.
115
+ - [ ] Body text and bubbles have a maximum width.
116
+ - [ ] Only things that were said are bubbles; events, tool calls and links use their own parts.
117
+ - [ ] Anything with detail opens an inspector, and a run's inspector shows its trace and logs.
118
+ - [ ] No hex colours, no default Tailwind colours, no cards in cards, no eyebrows, sentence case.
119
+ - [ ] Checked in dark mode and at phone width (390px).
@@ -0,0 +1,111 @@
1
+ "use client";
2
+
3
+ /*
4
+ * Recipe: the three-pane app shell. A list pane on the leading edge, the content in the middle, an inspector on the
5
+ * trailing edge, all inside `Panes` so they draw as glass over the window's wash. Pane tops line up at
6
+ * `spacing-pane-top` (12px) with 36px controls; the list pane owns its own search; the inspector owns its tabs.
7
+ */
8
+
9
+ import { useState } from "react";
10
+ import {
11
+ Avatar,
12
+ BodyText,
13
+ ContentPane,
14
+ EmptyPane,
15
+ FactRow,
16
+ HairlineList,
17
+ InspectorHeader,
18
+ InspectorPane,
19
+ LargeTitle,
20
+ ListPane,
21
+ ListRow,
22
+ ListRows,
23
+ Page,
24
+ PageSection,
25
+ PageTabBar,
26
+ PaneSearchField,
27
+ Panes,
28
+ SegmentedControl,
29
+ StatusPill,
30
+ UsersGroupRoundedIcon,
31
+ } from "@eigenhq/kern";
32
+
33
+ type Person = { id: string; name: string; role: string; lastSeen: string; status: "active" | "away" };
34
+
35
+ const PEOPLE: readonly Person[] = [
36
+ { id: "jane", name: "Jane Addams", role: "Curator", lastSeen: "2 min", status: "active" },
37
+ { id: "anton", name: "Anton Burger", role: "Painter", lastSeen: "1 h", status: "away" },
38
+ { id: "maya", name: "Maya Angelou", role: "Writer", lastSeen: "Yesterday", status: "active" },
39
+ ];
40
+
41
+ export function AppShell() {
42
+ const [search, setSearch] = useState("");
43
+ const [selectedId, setSelectedId] = useState<string | null>(PEOPLE[0].id);
44
+ const [tab, setTab] = useState<"about" | "activity">("about");
45
+ const shown = PEOPLE.filter((person) => person.name.toLowerCase().includes(search.trim().toLowerCase()));
46
+ const selected = PEOPLE.find((person) => person.id === selectedId) ?? null;
47
+ return (
48
+ <div className="h-[640px] w-full">
49
+ <Panes>
50
+ <ListPane label="People" header={<PaneSearchField value={search} onChange={setSearch} placeholder="Search" label="Search people" onClear={() => setSearch("")} />}>
51
+ <ListRows label="People">
52
+ {shown.map((person) => (
53
+ <ListRow
54
+ key={person.id}
55
+ avatar={<Avatar kind="person" name={person.name} sizePx={40} tint="name" />}
56
+ title={person.name}
57
+ subtitle={person.role}
58
+ trailing={person.lastSeen}
59
+ selected={person.id === selectedId}
60
+ onSelect={() => setSelectedId(person.id)}
61
+ />
62
+ ))}
63
+ </ListRows>
64
+ </ListPane>
65
+ <ContentPane label="Person">
66
+ {selected ? (
67
+ // The content's own padding: 16px at the sides, the large title 16px from the top.
68
+ <div className="flex flex-col gap-section overflow-y-auto px-4 pb-6">
69
+ <LargeTitle title={selected.name} detail={selected.role} trailing={<StatusPill label={selected.status} tone={selected.status === "active" ? "blue" : "muted"} />} />
70
+ <BodyText measure>
71
+ Long text sits in a measure of about 62 characters, so a line is easy to follow even when the pane is wide.
72
+ </BodyText>
73
+ </div>
74
+ ) : (
75
+ <EmptyPane icon={<UsersGroupRoundedIcon />}>Pick someone to see their details.</EmptyPane>
76
+ )}
77
+ </ContentPane>
78
+ {selected && (
79
+ <InspectorPane label="Person inspector">
80
+ <PageTabBar>
81
+ <SegmentedControl
82
+ label="Inspector"
83
+ value={tab}
84
+ onValueChange={setTab}
85
+ options={[
86
+ { value: "about", label: "About" },
87
+ { value: "activity", label: "Activity" },
88
+ ]}
89
+ />
90
+ </PageTabBar>
91
+ <Page>
92
+ <InspectorHeader variant="identity" leading={<Avatar kind="person" name={selected.name} sizePx={40} tint="name" />} title={selected.name} detail={`Last seen ${selected.lastSeen}`} />
93
+ {tab === "about" ? (
94
+ <PageSection variant="plain" title="Details">
95
+ <HairlineList>
96
+ <FactRow label="Role">{selected.role}</FactRow>
97
+ <FactRow label="Status">{selected.status}</FactRow>
98
+ </HairlineList>
99
+ </PageSection>
100
+ ) : (
101
+ <PageSection variant="plain" title="Activity">
102
+ <BodyText>No activity this week.</BodyText>
103
+ </PageSection>
104
+ )}
105
+ </Page>
106
+ </InspectorPane>
107
+ )}
108
+ </Panes>
109
+ </div>
110
+ );
111
+ }
@@ -0,0 +1,125 @@
1
+ "use client";
2
+
3
+ /*
4
+ * Recipe: a dashboard. The summary before the detail: a row of stat cards (the number large, its label and change
5
+ * small and grey, a sparkline beside it), then the charts in glass cards, then the table. Cards sit 12px apart in a grid
6
+ * that becomes one column on a phone; sections 32px apart. Every chart is inside a `ChartContainer` with a label that
7
+ * says what it shows. Status is a word on a pill, never colour alone.
8
+ */
9
+
10
+ import {
11
+ BarChart,
12
+ Card,
13
+ ChartContainer,
14
+ ChartKey,
15
+ LargeTitle,
16
+ LineChart,
17
+ SectionLabel,
18
+ Sparkline,
19
+ StatusPill,
20
+ Table,
21
+ TableBody,
22
+ TableCell,
23
+ TableHead,
24
+ TableHeader,
25
+ TableRow,
26
+ type ChartConfig,
27
+ type StatusPillTone,
28
+ } from "@eigenhq/kern";
29
+
30
+ const STATS = [
31
+ { label: "Runs today", value: "1,284", change: "+12% on yesterday", trend: [820, 940, 1010, 980, 1120, 1190, 1284] },
32
+ { label: "Passed the rubric", value: "91%", change: "+3 points", trend: [84, 86, 85, 88, 89, 90, 91] },
33
+ { label: "Median time", value: "8.2 s", change: "−0.6 s", trend: [9.4, 9.1, 9.0, 8.8, 8.6, 8.4, 8.2] },
34
+ ] as const;
35
+
36
+ const RUNS: ChartConfig = { passed: { label: "Passed" }, failed: { label: "Failed" } };
37
+ const RUNS_BY_DAY = [
38
+ { day: "Mon", passed: 940, failed: 80 },
39
+ { day: "Tue", passed: 1010, failed: 72 },
40
+ { day: "Wed", passed: 980, failed: 95 },
41
+ { day: "Thu", passed: 1120, failed: 61 },
42
+ { day: "Fri", passed: 1170, failed: 114 },
43
+ ];
44
+
45
+ const LATENCY: ChartConfig = { p50: { label: "Median" }, p95: { label: "95th percentile" } };
46
+ const LATENCY_BY_DAY = [
47
+ { day: "Mon", p50: 9.4, p95: 21.0 },
48
+ { day: "Tue", p50: 9.1, p95: 19.4 },
49
+ { day: "Wed", p50: 8.8, p95: 18.8 },
50
+ { day: "Thu", p50: 8.4, p95: 17.2 },
51
+ { day: "Fri", p50: 8.2, p95: 16.9 },
52
+ ];
53
+
54
+ const FAILURES: readonly { id: string; variant: string; criterion: string; count: number; status: string; tone: StatusPillTone }[] = [
55
+ { id: "1", variant: "Playlist tools off", criterion: "Claims a change it did not make", count: 41, status: "open", tone: "red" },
56
+ { id: "2", variant: "Playlist tools on", criterion: "Sends the link twice", count: 7, status: "review", tone: "amber" },
57
+ { id: "3", variant: "Playlist tools on", criterion: "Makes a second playlist", count: 2, status: "fixed", tone: "muted" },
58
+ ];
59
+
60
+ export function Dashboard() {
61
+ return (
62
+ <div className="flex w-full flex-col gap-section px-4 pb-10">
63
+ <LargeTitle title="Evaluations" detail="This week, across every variant." />
64
+ <section aria-label="Summary" className="grid gap-3 sm:grid-cols-3">
65
+ {STATS.map((stat) => (
66
+ <Card key={stat.label} className="flex items-end justify-between gap-3 p-4">
67
+ <div className="flex min-w-0 flex-col gap-1">
68
+ <span className="text-footnote text-label-secondary">{stat.label}</span>
69
+ <span className="text-large-title font-bold tabular-nums">{stat.value}</span>
70
+ <span className="text-caption text-label-secondary">{stat.change}</span>
71
+ </div>
72
+ <Sparkline values={stat.trend} label={`${stat.label}, last seven days`} />
73
+ </Card>
74
+ ))}
75
+ </section>
76
+ <section aria-label="Charts" className="grid gap-3 lg:grid-cols-2">
77
+ <Card className="flex flex-col gap-3 p-4">
78
+ <div className="flex items-center justify-between gap-3">
79
+ <SectionLabel title="Runs by day" className="px-0" />
80
+ <ChartKey config={RUNS} mark="square" />
81
+ </div>
82
+ <ChartContainer config={RUNS} label="Runs by day, passed and failed">
83
+ <BarChart data={RUNS_BY_DAY} categoryKey="day" layout="stacked" />
84
+ </ChartContainer>
85
+ </Card>
86
+ <Card className="flex flex-col gap-3 p-4">
87
+ <div className="flex items-center justify-between gap-3">
88
+ <SectionLabel title="Time per run, seconds" className="px-0" />
89
+ <ChartKey config={LATENCY} mark="line" />
90
+ </div>
91
+ <ChartContainer config={LATENCY} label="Time per run in seconds by day, median and 95th percentile">
92
+ <LineChart data={LATENCY_BY_DAY} xKey="day" fill="none" />
93
+ </ChartContainer>
94
+ </Card>
95
+ </section>
96
+ <section aria-label="Failures" className="flex flex-col gap-1.5">
97
+ <SectionLabel title="Most common failures" />
98
+ <Table>
99
+ <TableHeader>
100
+ <TableRow>
101
+ <TableHead>Variant</TableHead>
102
+ <TableHead>Criterion</TableHead>
103
+ <TableHead align="end">Runs</TableHead>
104
+ <TableHead align="end">Status</TableHead>
105
+ </TableRow>
106
+ </TableHeader>
107
+ <TableBody>
108
+ {FAILURES.map((failure) => (
109
+ <TableRow key={failure.id}>
110
+ <TableCell>{failure.variant}</TableCell>
111
+ <TableCell truncate>{failure.criterion}</TableCell>
112
+ <TableCell align="end" className="tabular-nums">
113
+ {failure.count}
114
+ </TableCell>
115
+ <TableCell align="end">
116
+ <StatusPill label={failure.status} tone={failure.tone} />
117
+ </TableCell>
118
+ </TableRow>
119
+ ))}
120
+ </TableBody>
121
+ </Table>
122
+ </section>
123
+ </div>
124
+ );
125
+ }
@@ -0,0 +1,50 @@
1
+ "use client";
2
+
3
+ /*
4
+ * Recipe: a single-page document, such as a report, a memo or an artifact a person reads top to bottom. One column at
5
+ * a reading measure (about 62 characters for body text), a title in the story face only when the page is a story or a
6
+ * title card (otherwise the interface face), headings by size and weight with no eyebrow over them, 32px between
7
+ * sections, a callout as an `Alert`, code in a `CodeBlock`, and a quote as a `Blockquote`. Plain prose is never inside a
8
+ * card.
9
+ */
10
+
11
+ import { Alert, Blockquote, CodeBlock, Heading, InlineCode, Lead, List, ListItem, Separator } from "@eigenhq/kern";
12
+
13
+ export function Document() {
14
+ return (
15
+ <article className="mx-auto flex w-full max-w-[720px] flex-col gap-section px-4 pb-12 pt-6">
16
+ <header className="flex flex-col gap-3">
17
+ <Heading level={1}>Why the playlist variant failed</Heading>
18
+ <Lead>
19
+ With the playlist tools turned off, the agent could only send single tracks, and it then told the person their
20
+ playlist was made. This note says what went wrong and what we changed.
21
+ </Lead>
22
+ </header>
23
+ <section className="flex flex-col gap-3">
24
+ <Heading level={2}>What happened</Heading>
25
+ <p className="max-w-[62ch] text-body leading-relaxed">
26
+ The rubric asks for one real playlist, sent once, and edited in place. None of that was reachable without the
27
+ tools, which is expected. The failure is the claim: asked whether the list was updated, the agent said the songs
28
+ were locked in.
29
+ </p>
30
+ <Blockquote variant="tint" cite="The agent, 19:07">
31
+ had the seven without redbone locked in on my end
32
+ </Blockquote>
33
+ </section>
34
+ <Alert tone="warning" title="Claims need a receipt" description="A reply that says something was done now has to cite the tool call that did it." />
35
+ <section className="flex flex-col gap-3">
36
+ <Heading level={2}>What we changed</Heading>
37
+ <List variant="number">
38
+ <ListItem>The agent is told which tools it has in this variant, by name.</ListItem>
39
+ <ListItem>
40
+ A reply with <InlineCode>done</InlineCode> or <InlineCode>locked in</InlineCode> must follow a successful write.
41
+ </ListItem>
42
+ <ListItem>The judge scores claims without a receipt as missed, not as unreachable.</ListItem>
43
+ </List>
44
+ <CodeBlock language="typescript" filename="claims.ts" code={`export function hasReceipt(reply: Reply, calls: ToolCall[]): boolean {\n return !claimsDone(reply) || calls.some((call) => call.kind === "write" && call.status === "done");\n}`} />
45
+ </section>
46
+ <Separator orientation="horizontal" variant="full" />
47
+ <p className="text-footnote text-label-secondary">Written 18 November 2026 · Evaluations</p>
48
+ </article>
49
+ );
50
+ }