@superjackfruitlabs/vibekit-docs 0.0.0-stage → 0.0.4

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.
@@ -0,0 +1,72 @@
1
+ ---
2
+ // The 404 with character: you've wandered off the street. Search, the docs home and the
3
+ // product's landing page are each one step away, and Captain Jack is there if the page was a
4
+ // question all along.
5
+ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
6
+ import { jack } from '@superjackfruitlabs/vibekit-frame/components/shadow.ts';
7
+ import { hostOf, productOf } from '../site.ts';
8
+
9
+ export const prerender = true;
10
+ const me = productOf();
11
+ const home = import.meta.env.BASE_URL;
12
+ ---
13
+ <StarlightPage frontmatter={{ title: "You've wandered off the street", template: 'splash', pagefind: false, editUrl: false, lastUpdated: false, prev: false, next: false }}>
14
+ <div class="sjl-404 not-content">
15
+ <div class="art" aria-hidden="true">
16
+ <span class="jack" set:html={jack()} />
17
+ <span class="sign">404</span>
18
+ <span class="road"></span>
19
+ </div>
20
+ <div class="say">
21
+ <p class="eyebrow">{me.name} docs · page not found</p>
22
+ <h2 class="sjl-display">You've wandered off the street.</h2>
23
+ <p>No page lives at this address. It may have moved when the docs were reorganised, or the link had a typo. Nothing is broken on your side.</p>
24
+ <form class="find" action={`${home}`} method="get" role="search" data-search>
25
+ <label class="sjl-sr-only" for="sjl-404-q">Search the {me.name} docs</label>
26
+ <input id="sjl-404-q" name="q" type="search" placeholder={`Search the ${me.name} docs…`} />
27
+ <button class="sjl-btn primary" type="submit">Search</button>
28
+ </form>
29
+ <div class="ways">
30
+ <a class="sjl-btn" href={home}>The docs home</a>
31
+ <a class="sjl-btn" href={me.landing}>{hostOf(me.landing)} <span aria-hidden="true">↗</span></a>
32
+ </div>
33
+ </div>
34
+ </div>
35
+ <script>
36
+ // Search opens Starlight's own search dialog with the words already typed.
37
+ const form = document.querySelector<HTMLFormElement>('.sjl-404 form[data-search]');
38
+ form?.addEventListener('submit', (e) => {
39
+ const q = (form.querySelector('input') as HTMLInputElement).value.trim();
40
+ const open = document.querySelector<HTMLButtonElement>('site-search button[data-open-modal]');
41
+ if (!open) return;
42
+ e.preventDefault();
43
+ open.click();
44
+ requestAnimationFrame(() => {
45
+ const input = document.querySelector<HTMLInputElement>('site-search dialog input');
46
+ if (input && q) { input.value = q; input.dispatchEvent(new Event('input', { bubbles: true })); }
47
+ });
48
+ });
49
+ </script>
50
+ </StarlightPage>
51
+
52
+ <style>
53
+ .sjl-404 { display: grid; grid-template-columns: minmax(0, 15rem) minmax(0, 1fr); gap: 2.5rem; align-items: center; margin-block: 3rem; }
54
+ .art { position: relative; height: 15rem; }
55
+ .jack { position: absolute; left: 0; bottom: 1.4rem; width: 9rem; }
56
+ .jack :global(svg) { width: 100%; height: auto; display: block; }
57
+ .sign { position: absolute; right: 0.5rem; top: 1.5rem; padding: 0.45rem 0.8rem; border-radius: 10px; background: var(--sjl-brand); color: var(--sjl-brand-ink); font: 800 1.6rem/1 var(--sjl-font-display); transform: rotate(6deg); box-shadow: 0 14px 30px -14px var(--sjl-glow); }
58
+ .road { position: absolute; left: 0; right: 0; bottom: 0; height: 0.9rem; border-radius: 4px; background: repeating-linear-gradient(90deg, var(--sl-color-gray-4) 0 18px, transparent 18px 30px) center / 100% 3px no-repeat, var(--sl-color-gray-6); }
59
+ .say { display: grid; gap: 0.9rem; }
60
+ .eyebrow { margin: 0; font: 600 0.72rem/1 var(--sl-font); letter-spacing: 0.12em; text-transform: uppercase; color: var(--sl-color-gray-3); }
61
+ h2 { margin: 0; font-size: clamp(2rem, 5vw, 3rem); line-height: 1.05; color: var(--sl-color-white); }
62
+ p { margin: 0; color: var(--sl-color-gray-2); max-width: 52ch; }
63
+ .find { display: flex; gap: 0.5rem; max-width: 30rem; }
64
+ .find input { flex: 1; min-width: 0; border: 1px solid var(--sl-color-gray-5); border-radius: 12px; padding: 0.6rem 0.75rem; background: var(--sl-color-gray-7); color: var(--sl-color-white); font: inherit; }
65
+ .find input:focus-visible { outline: 2px solid var(--sl-color-text-accent); outline-offset: 1px; }
66
+ .ways { display: flex; flex-wrap: wrap; gap: 0.5rem; }
67
+ @media (max-width: 40rem) {
68
+ .sjl-404 { grid-template-columns: 1fr; gap: 1rem; margin-block: 1rem; }
69
+ .art { height: 10rem; max-width: 16rem; }
70
+ .jack { width: 6.5rem; }
71
+ }
72
+ </style>
@@ -0,0 +1,17 @@
1
+ // Every docs page as Markdown at its own address, `<page>.md`, for an agent or a reader who wants
2
+ // the source. The same text Copy Markdown copies (src/markdown.ts).
3
+ import type { APIRoute, GetStaticPaths } from 'astro';
4
+ import { getCollection } from 'astro:content';
5
+ import { pageMarkdown } from '../markdown.ts';
6
+
7
+ export const prerender = true;
8
+
9
+ export const getStaticPaths = (async () => {
10
+ const docs = await getCollection('docs', (e) => !(e.data as { draft?: boolean }).draft);
11
+ return docs.map((e) => ({ params: { slug: e.id || 'index' }, props: { title: e.data.title, body: e.body } }));
12
+ }) satisfies GetStaticPaths;
13
+
14
+ export const GET: APIRoute = ({ props }) =>
15
+ new Response(pageMarkdown(props.title as string, props.body as string | undefined), {
16
+ headers: { 'content-type': 'text/markdown; charset=utf-8' },
17
+ });
@@ -0,0 +1,8 @@
1
+ // Types for schema.mjs, so a site's content.config.ts type-checks (`astro check`).
2
+ import type { docsSchema } from '@astrojs/starlight/schema';
3
+ import type { ZodType } from 'astro/zod';
4
+
5
+ /** "lit & steady", "lights on", "half-lit" or "wet paint" (or their keys); anything else fails the build. */
6
+ export declare const statusField: ZodType;
7
+ /** Starlight's docs schema plus `status:`. */
8
+ export declare function sjlDocsSchema(): ReturnType<typeof docsSchema>;
package/src/schema.mjs ADDED
@@ -0,0 +1,19 @@
1
+ // The docs collection's frontmatter: Starlight's own, plus `status:`, which puts a status badge
2
+ // beside the page title. In a site's src/content.config.ts:
3
+ //
4
+ // import { defineCollection } from 'astro:content';
5
+ // import { docsLoader } from '@astrojs/starlight/loaders';
6
+ // import { sjlDocsSchema } from '@superjackfruitlabs/vibekit-docs/schema';
7
+ // export const collections = { docs: defineCollection({ loader: docsLoader(), schema: sjlDocsSchema() }) };
8
+ import { docsSchema } from '@astrojs/starlight/schema';
9
+ import { z } from 'astro/zod';
10
+ import { STATUS_KEYS, STATUSES, statusOf } from './tokens.mjs';
11
+
12
+ /** "lit & steady", "lights on", "half-lit" or "wet paint" (or their keys); anything else fails the build. */
13
+ export const statusField = z
14
+ .string()
15
+ .refine((v) => statusOf(v) !== undefined, { message: `status must be one of: ${STATUS_KEYS.map((k) => STATUSES[k].label).join(', ')}` })
16
+ .transform((v) => statusOf(v))
17
+ .optional();
18
+
19
+ export const sjlDocsSchema = () => docsSchema({ extend: z.object({ status: statusField }) });
@@ -0,0 +1,19 @@
1
+ // Every suite docs site groups its pages the same way, so a reader who knows one knows them all:
2
+ // Start, Use it, Build on it, Run it, Reference, in that order. A site may leave a group out; any
3
+ // other top-level group, or the right groups out of order, is a warning at build time.
4
+
5
+ export const GROUPS = ['Start', 'Use it', 'Build on it', 'Run it', 'Reference'];
6
+
7
+ /** The warnings for a sidebar config; empty when it follows the suite's groups. */
8
+ export function sidebarWarnings(sidebar) {
9
+ if (!Array.isArray(sidebar)) return [];
10
+ const labels = sidebar.map((x) => (typeof x === 'object' && x && typeof x.label === 'string' ? x.label : null));
11
+ const out = [];
12
+ const odd = labels.filter((l) => l !== null && !GROUPS.includes(l));
13
+ if (odd.length) out.push(`top-level sidebar groups ${odd.map((l) => `"${l}"`).join(', ')} are not one of ${GROUPS.join(' / ')}`);
14
+ if (labels.some((l) => l === null)) out.push('a top-level sidebar entry is a page, not a group; put it under one of ' + GROUPS.join(' / '));
15
+ const known = labels.filter((l) => l !== null && GROUPS.includes(l));
16
+ const order = known.map((l) => GROUPS.indexOf(l));
17
+ if (order.some((n, i) => i > 0 && n <= order[i - 1])) out.push(`sidebar groups should run ${GROUPS.join(', ')}; these run ${known.join(', ')}`);
18
+ return out;
19
+ }
package/src/site.ts ADDED
@@ -0,0 +1,52 @@
1
+ // What every component knows about the site it is on: the product (from the plugin, through a
2
+ // virtual module), and the suite's product list. A component's own `product` prop wins, so a
3
+ // component can also be rendered outside a themed site (the tests do).
4
+ import theme from 'virtual:sjl-docs/theme';
5
+ import { ORDER, PRODUCTS } from '@superjackfruitlabs/vibekit-frame/data';
6
+ import { STATUSES, statusOf } from './tokens.mjs';
7
+
8
+ export { STATUSES, statusOf };
9
+
10
+ /** The suite, in street order. */
11
+ export const SUITE = { order: ORDER, products: PRODUCTS };
12
+
13
+ /**
14
+ * What a component is for: its prop, else the site's. A product gives its frontdoor record. A site
15
+ * that is not a product (the plugin's `site` option, such as Treaty) gives the same fields, and is
16
+ * never a house on the street: `product` is false, its colour is the accent it wears
17
+ * (`--sjl-brand`), and its mark is the mark of whose look it wears (the lab's).
18
+ */
19
+ export function productOf(prop?: string) {
20
+ const site = theme?.site;
21
+ if (site && (prop === undefined || prop === site.slug)) {
22
+ return { ...site, color: 'var(--sjl-brand)', role: site.line, mark: site.wears, product: false as const };
23
+ }
24
+ const slug = prop ?? theme?.product;
25
+ const p = SUITE.products[slug];
26
+ if (!p) throw new Error(`docs-theme: unknown product "${slug}"`);
27
+ return { ...p, slug, mark: slug, landing: p.url, product: true as const };
28
+ }
29
+
30
+ /** The site's own status word (the plugin's `status` option), or null. */
31
+ export const siteStatus = () => theme?.status ?? null;
32
+
33
+ /** Where a product's landing page is, as the reader says it: "superdispatch.dev". */
34
+ export const hostOf = (url) => new URL(url).hostname;
35
+
36
+ /**
37
+ * Starlight's route data, or undefined where there is none: starlight-llms-txt renders page
38
+ * content outside a Starlight route, and Starlight's getter throws there.
39
+ */
40
+ export function routeOf(locals: unknown): any {
41
+ try { return (locals as { starlightRoute?: unknown }).starlightRoute; } catch { return undefined; }
42
+ }
43
+
44
+ /**
45
+ * Whether a page wears frontdoor's full suite footer: only the docs home and the 404. Every other
46
+ * page ends with the quiet line instead.
47
+ */
48
+ export function wearsSuiteFooter(route: any): boolean {
49
+ if (!route) return false;
50
+ // Starlight's id for the docs home is '' (index.mdx); the theme's 404 page is '404'.
51
+ return route.id === '' || route.id === '404';
52
+ }
package/src/steps.ts ADDED
@@ -0,0 +1,8 @@
1
+ // Ids for a step component's tabs and panels: unique on the page, so two FlowSteps (or a
2
+ // FlowSteps and a DecisionReplay) never point at each other's panels.
3
+ let seq = 0;
4
+ export function stepIds(prefix: string, n: number) {
5
+ const base = `sjl-${prefix}-${(++seq).toString(36)}${Math.random().toString(36).slice(2, 6)}`;
6
+ if (n < 1) throw new Error('docs-theme: a step component needs at least one step');
7
+ return { base, tab: (i: number) => `${base}-tab-${i}`, panel: (i: number) => `${base}-panel-${i}` };
8
+ }
@@ -0,0 +1,13 @@
1
+ /* The suite's docs faces, self-hosted: the font files are bundled into each site at build time,
2
+ so no page asks Google (or anyone) for a font. Bricolage Grotesque for display, with its
3
+ optical-size axis; IBM Plex Sans for body; IBM Plex Mono for code. Latin and Latin Extended
4
+ only: every product's docs are written in English. */
5
+ @import '@fontsource-variable/bricolage-grotesque/opsz.css';
6
+ @import '@fontsource/ibm-plex-sans/latin-400.css';
7
+ @import '@fontsource/ibm-plex-sans/latin-ext-400.css';
8
+ @import '@fontsource/ibm-plex-sans/latin-400-italic.css';
9
+ @import '@fontsource/ibm-plex-sans/latin-500.css';
10
+ @import '@fontsource/ibm-plex-sans/latin-600.css';
11
+ @import '@fontsource/ibm-plex-sans/latin-ext-600.css';
12
+ @import '@fontsource/ibm-plex-mono/latin-400.css';
13
+ @import '@fontsource/ibm-plex-mono/latin-500.css';
@@ -0,0 +1,212 @@
1
+ /*
2
+ * The suite's docs theme. The colours themselves are generated per product from vibekit (the
3
+ * plugin writes them into a <style> in the head: the grey scale, the accent triple Starlight
4
+ * derives everything else from, the brand colour and the status fills). This file only says
5
+ * where they go, and sets the faces and the shapes.
6
+ *
7
+ * `html:root` rather than `:root` is load-bearing: this file can be bundled ahead of Starlight's
8
+ * own props.css, and at equal specificity Starlight's defaults would win with a build that
9
+ * succeeds and a page that looks untouched.
10
+ */
11
+ html:root {
12
+ --sl-font: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
13
+ --sl-font-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', monospace;
14
+ --sjl-font-display: 'Bricolage Grotesque Variable', 'Bricolage Grotesque', 'Avenir Next', system-ui, sans-serif;
15
+ --sjl-radius: 18px;
16
+ --sjl-glow: color-mix(in oklab, var(--sjl-brand) 38%, transparent);
17
+ --sjl-soft: color-mix(in oklab, var(--sjl-brand) 14%, var(--sl-color-gray-7));
18
+ /* The street sits above Starlight's own bar, so the header is taller. */
19
+ --sjl-street-height: 2.5rem;
20
+ --sl-nav-height: calc(3.5rem + var(--sjl-street-height));
21
+ }
22
+ @media (max-width: 49.99rem) {
23
+ html:root { --sjl-street-height: 2.25rem; }
24
+ }
25
+
26
+ /* ---- faces -------------------------------------------------------------------------------- */
27
+ .sl-markdown-content :is(h1, h2, h3, h4),
28
+ .content-panel h1,
29
+ .sjl-display {
30
+ font-family: var(--sjl-font-display);
31
+ font-weight: 700;
32
+ letter-spacing: -0.02em;
33
+ font-optical-sizing: auto;
34
+ }
35
+ .sl-markdown-content h2 { letter-spacing: -0.025em; }
36
+
37
+ /* ---- the filled accent in light reads white ------------------------------------------------- */
38
+ /* Starlight sets a filled button's text in --sl-color-black, which in light is the page; white
39
+ reads better on the deep accent, and matches the current sidebar item (text-invert). */
40
+ html:root[data-theme='light'] .sl-link-button.primary,
41
+ html:root[data-theme='light'] .sl-link-button.primary:hover {
42
+ color: #ffffff;
43
+ }
44
+
45
+ /* ---- one accent: notes, cards, the current item ---------------------------------------------- */
46
+ .starlight-aside--note {
47
+ --sl-color-asides-text-accent: var(--sl-color-accent-high);
48
+ --sl-color-asides-border: var(--sl-color-accent);
49
+ background-color: var(--sl-color-accent-low);
50
+ }
51
+ .sl-markdown-content .card,
52
+ .card {
53
+ --sl-card-border: var(--sl-color-accent);
54
+ --sl-card-bg: var(--sl-color-accent-low);
55
+ border-radius: 14px;
56
+ }
57
+
58
+ /* ---- tables (Treaty's rules): wide tables scroll inside the page, never the page ---------- */
59
+ .sl-markdown-content table {
60
+ display: block;
61
+ overflow-x: auto;
62
+ max-width: 100%;
63
+ }
64
+ .sl-markdown-content table code { white-space: nowrap; }
65
+ .sl-markdown-content td { min-width: 7rem; }
66
+ .sl-markdown-content table td:last-child code { white-space: normal; overflow-wrap: anywhere; }
67
+
68
+ /* ---- code ------------------------------------------------------------------------------------ */
69
+ .sl-markdown-content :not(pre) > code {
70
+ border-radius: 6px;
71
+ padding: 0.1em 0.35em;
72
+ }
73
+
74
+ /* ---- status badge ---------------------------------------------------------------------------- */
75
+ .sjl-status {
76
+ --_fill: var(--sjl-status-lights-on);
77
+ display: inline-flex;
78
+ align-items: center;
79
+ gap: 0.45em;
80
+ padding: 0.3em 0.7em 0.3em 0.6em;
81
+ border-radius: 999px;
82
+ background: var(--_fill);
83
+ color: var(--sjl-status-ink);
84
+ font: 600 0.75rem/1 var(--sl-font);
85
+ letter-spacing: 0.01em;
86
+ white-space: nowrap;
87
+ text-decoration: none;
88
+ vertical-align: middle;
89
+ }
90
+ .sjl-status::before {
91
+ content: '';
92
+ width: 0.55em;
93
+ height: 0.55em;
94
+ border-radius: 50%;
95
+ background: color-mix(in oklab, var(--_fill) 45%, var(--sjl-status-ink));
96
+ box-shadow: 0 0 0 2px color-mix(in oklab, var(--_fill) 60%, transparent);
97
+ }
98
+ .sjl-status[data-status='wet-paint'] { --_fill: var(--sjl-status-wet-paint); }
99
+ .sjl-status[data-status='half-lit'] { --_fill: var(--sjl-status-half-lit); }
100
+ .sjl-status[data-status='lights-on'] { --_fill: var(--sjl-status-lights-on); }
101
+ .sjl-status[data-status='lit-and-steady'] { --_fill: var(--sjl-status-lit-and-steady); }
102
+
103
+ /* ---- a splash home draws its own title: the panel holding the screen-reader h1 takes no room */
104
+ .content-panel:has(> .sl-container > h1.sjl-sr-only:only-child) {
105
+ padding-block: 0;
106
+ border-top: 0;
107
+ }
108
+ .content-panel:has(> .sl-container > h1.sjl-sr-only:only-child) + .content-panel { border-top: 0; }
109
+
110
+ /* ---- small shared bits ----------------------------------------------------------------------- */
111
+ .sjl-sr-only {
112
+ position: absolute;
113
+ width: 1px;
114
+ height: 1px;
115
+ padding: 0;
116
+ margin: -1px;
117
+ overflow: hidden;
118
+ clip: rect(0, 0, 0, 0);
119
+ white-space: nowrap;
120
+ border: 0;
121
+ }
122
+ .sjl-btn {
123
+ display: inline-flex;
124
+ align-items: center;
125
+ gap: 0.5rem;
126
+ border-radius: 12px;
127
+ padding: 0.6rem 1rem;
128
+ font: 600 0.95rem/1.2 var(--sl-font);
129
+ border: 1px solid var(--sl-color-gray-5);
130
+ background: var(--sl-color-gray-7);
131
+ color: var(--sl-color-white);
132
+ text-decoration: none;
133
+ cursor: pointer;
134
+ }
135
+ /* Touch: every button in the theme is at least 44px tall. */
136
+ @media (pointer: coarse) { .sjl-btn { min-height: 44px; } }
137
+ /* An author `display` would beat the hidden attribute; a hidden button stays hidden. */
138
+ .sjl-btn[hidden] { display: none; }
139
+ .sjl-btn:hover { border-color: var(--sjl-brand); color: var(--sl-color-white); }
140
+ .sjl-btn.primary {
141
+ background: var(--sl-color-text-accent);
142
+ color: var(--sl-color-text-invert);
143
+ border-color: transparent;
144
+ box-shadow: 0 10px 30px -12px var(--sjl-glow);
145
+ }
146
+ .sjl-btn.primary:hover { color: var(--sl-color-text-invert); filter: brightness(1.06); }
147
+ .sjl-btn:focus-visible,
148
+ .sjl-focus:focus-visible {
149
+ outline: 2px solid var(--sl-color-text-accent);
150
+ outline-offset: 2px;
151
+ }
152
+
153
+ @media (prefers-reduced-motion: reduce) {
154
+ .sjl-motion,
155
+ .sjl-motion * { transition: none !important; animation: none !important; }
156
+ }
157
+
158
+ /* ---- steps: the tablist FlowSteps and DecisionReplay share (src/client/steps.ts) -------------- */
159
+ .sjl-steps { display: grid; gap: 0.75rem; }
160
+ .sjl-steps-tabs { display: grid; grid-template-columns: repeat(var(--n), minmax(0, 1fr)); gap: 0.4rem; }
161
+ .sjl-steps-tabs[hidden], .sjl-steps-controls[hidden] { display: none; }
162
+ .sjl-step-tab {
163
+ display: flex;
164
+ align-items: center;
165
+ justify-content: center;
166
+ gap: 0.45rem;
167
+ min-height: 44px;
168
+ min-width: 44px;
169
+ padding: 0.35rem 0.5rem;
170
+ border: 1px solid var(--sl-color-gray-5);
171
+ border-radius: 12px;
172
+ background: var(--sl-color-gray-7);
173
+ color: var(--sl-color-gray-2);
174
+ font: 600 0.85rem/1.1 var(--sl-font);
175
+ cursor: pointer;
176
+ }
177
+ .sjl-step-tab .num {
178
+ display: inline-grid;
179
+ place-items: center;
180
+ flex: none;
181
+ width: 1.5rem;
182
+ height: 1.5rem;
183
+ border-radius: 999px;
184
+ background: var(--sl-color-gray-6);
185
+ font: 700 0.75rem/1 var(--sl-font);
186
+ font-variant-numeric: tabular-nums;
187
+ }
188
+ .sjl-step-tab:hover { border-color: var(--sjl-brand); color: var(--sl-color-white); }
189
+ .sjl-step-tab[aria-selected='true'] { border-color: var(--sjl-brand); background: var(--sjl-soft); color: var(--sl-color-white); }
190
+ .sjl-step-tab[aria-selected='true'] .num { background: var(--sl-color-text-accent); color: var(--sl-color-text-invert); }
191
+ .sjl-step-tab:focus-visible,
192
+ .sjl-step-panel:focus-visible,
193
+ .sjl-step-btn:focus-visible { outline: 2px solid var(--sl-color-text-accent); outline-offset: 2px; }
194
+ .sjl-steps-panels { display: grid; gap: 0.5rem; }
195
+ .sjl-step-panel { margin: 0; font-size: 0.9rem; line-height: 1.55; background: var(--sl-color-gray-6); border-radius: 12px; padding: 0.75rem 0.9rem; color: var(--sl-color-gray-2); }
196
+ .sjl-step-panel b { color: var(--sl-color-white); }
197
+ .sjl-step-panel[hidden] { display: none; }
198
+ .sjl-steps-controls { display: flex; align-items: center; justify-content: space-between; gap: 0.75rem; }
199
+ .sjl-step-btn { min-height: 44px; min-width: 6.5rem; justify-content: center; }
200
+ .sjl-step-btn[aria-disabled='true'] { opacity: 0.45; cursor: default; }
201
+ .sjl-step-btn[aria-disabled='true']:hover { border-color: var(--sl-color-gray-5); }
202
+ .sjl-steps-count { font-size: 0.82rem; color: var(--sl-color-gray-3); font-variant-numeric: tabular-nums; }
203
+ @media (prefers-reduced-motion: no-preference) {
204
+ .sjl-step-tab, .sjl-step-tab .num { transition: background-color 0.2s, border-color 0.2s, color 0.2s; }
205
+ }
206
+ /* A phone: the numbers stay, and a label that does not fit gives way to the selected step's. */
207
+ @media (max-width: 30rem) {
208
+ .sjl-step-tab { padding-inline: 0.25rem; }
209
+ /* Clipped, not removed: the label stays the tab's name for a screen reader. */
210
+ .sjl-step-tab:not([aria-selected='true']) .lbl { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
211
+ .sjl-steps-tabs { grid-template-columns: repeat(var(--n), auto); justify-content: space-between; }
212
+ }
package/src/tokens.mjs ADDED
@@ -0,0 +1,113 @@
1
+ // The theme's colours. Every colour a product owns comes from vibekit: its accent (PRODUCT_ACCENTS
2
+ // names it, accents.css holds its Daylight values for light and dark) and the status colours (the
3
+ // mood fills of tokens.css). The one thing the theme owns is the neutral grey scale, the same on
4
+ // every docs site, so the products differ only by their accent. No product colour is typed here.
5
+ //
6
+ // Pure functions over the CSS text, so the tests can run them on vibekit's real files.
7
+
8
+ export const THEMES = ['light', 'dark'];
9
+ export const VIBE = 'daylight';
10
+
11
+ /** The custom properties of the first block whose selector list contains `selector`. */
12
+ export function block(css, selector) {
13
+ const at = css.indexOf(selector);
14
+ if (at < 0) throw new Error(`docs-theme: vibekit CSS has no ${selector}`);
15
+ const body = css.slice(css.indexOf('{', at) + 1, css.indexOf('}', at));
16
+ return Object.fromEntries([...body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)].map((m) => [m[1], m[2].trim().toLowerCase()]));
17
+ }
18
+
19
+ const need = (vars, name, where) => {
20
+ const v = vars[name];
21
+ if (!v || !/^#[0-9a-f]{6}$/.test(v)) throw new Error(`docs-theme: ${where} has no ${name} as #rrggbb`);
22
+ return v;
23
+ };
24
+
25
+ /** One theme's product accent, as vibekit's Daylight look draws it. */
26
+
27
+ export function accentOf(accentsCss, accent, theme) {
28
+ const sel = `[data-vibe="${VIBE}"][data-theme="${theme}"][data-accent="${accent}"]`;
29
+ const v = block(accentsCss, sel);
30
+ return { accent: need(v, '--vk-color-accent', sel), fg: need(v, '--vk-color-accent-fg', sel), wash: need(v, '--vk-color-accent-wash', sel), text: need(v, '--vk-color-accent-text', sel) };
31
+ }
32
+
33
+ /** What each status word means, in the order a product grows through them. */
34
+ export const STATUSES = {
35
+ 'wet-paint': { label: 'wet paint', means: 'New or experimental.', mood: 'needs' },
36
+ 'half-lit': { label: 'half-lit', means: 'Works, with known gaps the page names.', mood: 'done' },
37
+ 'lights-on': { label: 'lights on', means: 'In production, still changing.', mood: 'thinking' },
38
+ 'lit-and-steady': { label: 'lit & steady', means: 'In production, stable, relied on daily.', mood: 'working' },
39
+ };
40
+ export const STATUS_KEYS = Object.keys(STATUSES);
41
+
42
+ /** Accepts the key or the word a writer would type ("lit & steady", "wet paint"). */
43
+ export function statusOf(value) {
44
+ if (typeof value !== 'string') return undefined;
45
+ const v = value.trim().toLowerCase();
46
+ return STATUS_KEYS.find((k) => k === v || STATUSES[k].label === v || k.replace(/-/g, ' ') === v);
47
+ }
48
+
49
+ /** The status fills (vibekit's mood colours) and the ink that reads on them (its face ink). */
50
+ export function statusColours(tokensCss, theme) {
51
+ const sel = `[data-vibe="${VIBE}"][data-theme="${theme}"]`;
52
+ const v = block(tokensCss, sel);
53
+ const out = Object.fromEntries(STATUS_KEYS.map((k) => [k, need(v, `--vk-mood-${STATUSES[k].mood}`, sel)]));
54
+ // Face ink: the Daylight light text colour, which vibekit keeps at 4.5:1 on every mood in both themes.
55
+ const ink = need(block(tokensCss, `[data-vibe="${VIBE}"][data-theme="light"]`), '--vk-color-text', 'daylight light');
56
+ return { ...out, ink };
57
+ }
58
+
59
+ /** The neutral grey scale every docs site shares, from page text (white) to the page itself (black), Starlight's way. */
60
+ export const GREYS = {
61
+ dark: {
62
+ white: '#f2f0f7', 'gray-1': '#e4e2ea', 'gray-2': '#c9c6d2', 'gray-3': '#a3a0ad', 'gray-4': '#62606c',
63
+ 'gray-5': '#2c2b34', 'gray-6': '#1a1a20', 'gray-7': '#131317', black: '#0d0d11',
64
+ },
65
+ light: {
66
+ white: '#16151a', 'gray-1': '#26252b', 'gray-2': '#3b3a41', 'gray-3': '#5e5b66', 'gray-4': '#8d8a94',
67
+ 'gray-5': '#dedad3', 'gray-6': '#efece6', 'gray-7': '#ffffff', black: '#f7f6f3',
68
+ },
69
+ };
70
+
71
+ // ---- colour arithmetic (sRGB, WCAG 2) --------------------------------------------------------
72
+
73
+ const channels = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
74
+ const lin = (c) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
75
+ export const luminance = (hex) => { const [r, g, b] = channels(hex).map(lin); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
76
+ export const contrast = (a, b) => { const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); };
77
+ /** `a` mixed toward `b` by `t` (0..1), per sRGB channel. */
78
+ export const mix = (a, b, t) => {
79
+ const [p, q] = [channels(a), channels(b)];
80
+ return `#${p.map((c, i) => Math.round(c + (q[i] - c) * t).toString(16).padStart(2, '0')).join('')}`;
81
+ };
82
+
83
+ /** Every colour the theme sets, per theme. */
84
+
85
+ export function paletteOf(accentsCss, tokensCss, accent, theme) {
86
+ const a = accentOf(accentsCss, accent, theme);
87
+ const greys = GREYS[theme];
88
+ const status = statusColours(tokensCss, theme);
89
+ if (theme === 'dark') {
90
+ // Links read accent-high on the dark page; a filled accent (the current sidebar item, the
91
+ // primary button) carries the page's own black.
92
+ return { greys, accentLow: a.wash, accent: a.accent, accentHigh: a.text, textInvert: greys.black, brand: a.accent, brandInk: greys.black, status };
93
+ }
94
+ // In light, Starlight writes links in --sl-color-accent, so that is vibekit's accent-text (4.5:1
95
+ // on the page); accent-high, for text on the pale wash, is the same hue taken a third darker.
96
+ return { greys, accentLow: a.wash, accent: a.text, accentHigh: mix(a.text, '#000000', 0.33), textInvert: '#ffffff', brand: a.accent, brandInk: '#ffffff', status };
97
+ }
98
+
99
+ const decls = (p) => [
100
+ ...Object.entries(p.greys).map(([k, v]) => `--sl-color-${k}: ${v};`),
101
+ `--sl-color-accent-low: ${p.accentLow};`, `--sl-color-accent: ${p.accent};`, `--sl-color-accent-high: ${p.accentHigh};`,
102
+ `--sl-color-text-invert: ${p.textInvert};`,
103
+ `--sjl-brand: ${p.brand};`, `--sjl-brand-ink: ${p.brandInk};`,
104
+ ...STATUS_KEYS.map((k) => `--sjl-status-${k}: ${p.status[k]};`), `--sjl-status-ink: ${p.status.ink};`,
105
+ ].join(' ');
106
+
107
+ /**
108
+ * The colour tokens for one product, as CSS: dark on html:root (Starlight's default) and light under
109
+ * [data-theme='light']. `html:root` outranks Starlight's own :root defaults whatever the bundle order.
110
+ */
111
+ export function themeCss(accentsCss, tokensCss, accent) {
112
+ return `html:root { ${decls(paletteOf(accentsCss, tokensCss, accent, 'dark'))} }\nhtml:root[data-theme='light'] { ${decls(paletteOf(accentsCss, tokensCss, accent, 'light'))} }`;
113
+ }