create-obsidian-arrow 0.2.2 → 0.3.0

package/README.md

@@ -68,10 +68,11 @@ node create-obsidian-arrow/index.mjs update ../my-app   # update
 ## What you get
 
 A full sandbox: client-only Vite + TS, `@arrow-js/core` + `@arrow-js/framework`
-(no SSR), `routeToPage` + Navigation-API router with an `/example` demo, Biome +
-husky pre-commit + `node:test` + GitHub Actions CI, a `skills:install` that pulls
-the agent skills from the published repo, and the `pull-css` script that extracts
-Obsidian's `app.css`.
+(no SSR), `routeToPage` + Navigation-API router, a Storybook-style component
+viewer at `/components` (co-locate `*.stories.ts` to add stories), a live token
+and class reference at `/reference`, Biome + husky pre-commit + `node:test` +
+GitHub Actions CI, a `skills:install` that pulls the agent skills from the
+published repo, and the `pull-css` script that extracts Obsidian's `app.css`.
 
 ## Maintaining the template
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-obsidian-arrow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Scaffold an Obsidian-styled Arrow.js UI sandbox (pnpm create obsidian-arrow <dir>).",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -10,9 +10,13 @@ This file is the hub — everything else is linked from here:
 
 - [`docs/workflow.md`](docs/workflow.md) — fresh-machine → running workflow.
 - [`skills/`](skills/) — installable domain skills (`pnpm skills:install`):
-  obsidian-arrow-sandbox, arrow-js-obsidian-templates, arrow-js-obsidian-patterns,
-  arrow-js-obsidian-porting (sandbox→plugin parity check), obsidian-arrow-maintenance
-  (updating an existing project).
+  - `obsidian-arrow-sandbox` — running the sandbox, CSS scoping, porting basics.
+  - `obsidian-arrow-stories` — **component + story authoring workflow**: `defineStories` API, variants, children, status flag, DRY patterns, utilities.
+  - `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes → oas-* utilities → custom CSS; token reference; specificity scoping; overrides via variables; auditing for excess CSS.
+  - `arrow-js-obsidian-templates` — Arrow v1.0.6 template syntax + footguns.
+  - `arrow-js-obsidian-patterns` — icons, CSS scoping, lifecycle, reactive state.
+  - `arrow-js-obsidian-porting` — sandbox→plugin parity check (`component-hash`).
+  - `obsidian-arrow-maintenance` — updating an existing project.
 - [`docs/prompts/`](docs/prompts/) — copy-paste agent prompts: `agent-setup.md`
   (scaffold + orient) and `update-existing.md` (update tooling + skills, keep src).
 
@@ -78,6 +82,20 @@ events via `@event` (`@click="${fn}"`), keyed lists via
 `html\`…\`.key(id)`, async sections via `component(asyncFn, { fallback })` wrapped
 in `boundary()`.
 
+## Conventions
+
+- **Check `/reference/classes` first** — Obsidian has semantic classes for most
+  common patterns. Use them before writing any custom CSS.
+- **Use `oas-*` utilities second** (`src/utilities.css`) — flex, gap, padding,
+  margin, typography, border, overflow helpers built on Obsidian's token scale.
+  Prefer `class="oas-flex oas-gap-2"` over `style="display:flex;gap:8px"`.
+- **Custom CSS last** — only when Obsidian has no class and utilities don't cover
+  it. Scope under container + element type, use `var(--…)` tokens for values.
+- Add a story by creating a co-located `*.stories.ts` next to the component —
+  it appears at `/components/<slug>` automatically. See the `obsidian-arrow-stories`
+  skill for the full `defineStories` API (variants, children, status, notes).
+  Browse live tokens at `/reference`, curated classes at `/reference/classes`.
+
 ## CSS scoping
 
 - Use Obsidian's own classes (`.setting-item`, `.clickable-icon`,
@@ -109,3 +127,9 @@ mount it from `ItemView.onOpen()` via `template(this.contentEl)`. If it uses
 `boundary()`/async components, add `@arrow-js/framework` to the plugin and the
 `import '@arrow-js/framework'` side-effect import. Strip any sandbox chrome
 (`src/sandbox/*`) — that stays here.
+
+**Bring `src/utilities.css` along.** Components may use `oas-`-prefixed utility
+classes (flex, gap, padding, typography, border — all built on Obsidian's token
+scale). Copy `src/utilities.css` once into the plugin's styles directory and
+import it there. The `oas-` prefix guarantees no conflict with Obsidian selectors.
+Re-copy when the sandbox file changes (the porting-parity skill covers this).

package/template/README.md

@@ -91,7 +91,9 @@ skills under [`skills/`](skills/) — it's a skill marketplace. Scaffolds **don'
 vendor copies**; they pull from this published repo, so installs are always
 current.
 
-- `obsidian-arrow-sandbox` — running and using this sandbox, and porting to a plugin.
+- `obsidian-arrow-sandbox` — running and using this sandbox, CSS scoping, porting basics.
+- `obsidian-arrow-stories` — **component + story authoring workflow**: the complete `defineStories` API (variants, children, status flag, notes), DRY patterns, utility classes, story viewing, and how to structure sub-components.
+- `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes first, `oas-*` utilities second, custom CSS last; the live token reference (`/reference`), class catalog (`/reference/classes`), specificity scoping, overrides via CSS variables, and auditing components to minimize hand-written CSS.
 - `arrow-js-obsidian-templates` — Arrow v1.0.6 template rules + footguns.
 - `arrow-js-obsidian-patterns` — integration patterns: icons (Lucide / data-icon
   sweep), CSS scoping vs Obsidian globals, mount/unmount lifecycle, reactive state.
@@ -125,6 +127,38 @@ different project root, e.g. an outer repo a scaffold is nested in), `--global`
 forms `SKILLS_AGENT` / `SKILLS_PROJECT_DIR` / `SKILLS_GLOBAL` (and
 `SKIP_SKILLS_INSTALL=1`) influence *that* path.
 
+## Component viewer & reference
+
+**Component viewer (`/components`):** a Storybook-style browser for sandbox
+components. Co-locate a `*.stories.ts` file next to any component and it appears
+in the sidebar and on Home automatically. Stories support named variants,
+drill-in via `children` slugs, and a derived src path shown in the viewer — all
+discovered at build time via `import.meta.glob`.
+
+**Reference index (`/reference`):** all `var(--)` tokens parsed live from
+`app.css`, grouped by category (Size & spacing, Radius, Colors, …) with color
+swatches, size bars, a filter input, theme-aware resolved values, and a copy
+button. `/reference/classes` is a curated catalog of Obsidian pattern classes
+with live previews.
+
+### Add a story
+
+Create `src/components/MyThing.stories.ts` next to the component:
+
+```ts
+import { defineStories } from "../viewer/stories";
+import { MyThing } from "./MyThing";
+
+export default defineStories({
+	description: "What it demonstrates.",
+	variants: { default: () => MyThing() },
+});
+```
+
+It appears in the sidebar and on Home automatically; the src path shown in the
+viewer is derived from the file location. Stories are sandbox-only — they never
+port to the plugin.
+
 ## Porting a component into the plugin
 
 Components use only Obsidian classes + `var(--…)` tokens and mount via
@@ -133,6 +167,11 @@ copy the component file into the plugin's view directory and mount it from
 `onOpen()`. If it uses `boundary()`/async components, add `@arrow-js/framework`
 to the plugin and the `import '@arrow-js/framework'` side-effect import.
 
+Also copy `src/utilities.css` into the plugin once — components may use `oas-`
+utility classes (flex, gap, padding, typography, border helpers built on
+Obsidian's token scale). The `oas-` prefix means no conflicts with Obsidian's
+own selectors. All ported components in a plugin share one copy of this file.
+
 ## Arrow v1.0.6 footguns (learned the hard way)
 
 These are enforced/encoded so they don't regress:

package/template/_gitignore

@@ -10,3 +10,6 @@ dist
 # Obsidian's app.css is proprietary — extract it locally with `pnpm pull-css`,
 # don't commit/redistribute it.
 public/app.css
+
+# subagent-driven-development scratch (briefs, reports, ledger)
+.superpowers/

package/template/docs/prompts/agent-setup.md

@@ -30,7 +30,8 @@ Then:
                     # committed; it's Obsidian's proprietary CSS). Auto-detect is
                     # macOS-only; on Windows/WSL pass --path <obsidian.asar|app.css>
                     # or set OBSIDIAN_ASAR=<path>.
-  pnpm dev          # open the printed URL: / is the examples index, /example the demo.
+  pnpm dev          # open the printed URL: / is home, /components the story viewer,
+                    # /reference the Obsidian token/class index.
                     # The toolbar slider/presets + edge drag handle resize the panel.
   pnpm skills:install --yes   # install all agent skills non-interactively, pulled
                               # from the published repo (not vendored) — this loads
@@ -42,11 +43,17 @@ Then:
 READ FIRST
 - AGENTS.md (root) — operating guide + docs map (links everything below).
 - docs/workflow.md — fresh-machine → running workflow.
-- skills/*/SKILL.md — obsidian-arrow-sandbox (workflow), arrow-js-obsidian-
-  templates (template syntax + footguns), arrow-js-obsidian-patterns (icons via
-  Lucide/data-icon sweep, CSS scoping, mount/unmount lifecycle, reactive state),
-  arrow-js-obsidian-porting (sandbox→plugin parity check),
-  obsidian-arrow-maintenance (updating an existing project).
+- skills/*/SKILL.md — seven installable skills:
+    obsidian-arrow-sandbox    running the sandbox, CSS scoping, porting basics
+    obsidian-arrow-stories    component + story authoring: defineStories API,
+                              variants, children, status, DRY patterns, utilities
+    obsidian-arrow-css        CSS decision hierarchy: Obsidian classes → oas-*
+                              utilities → custom CSS; token/class reference;
+                              scoping rules; overrides via variables; CSS audit
+    arrow-js-obsidian-templates  template syntax + hard footguns
+    arrow-js-obsidian-patterns   icons, CSS scoping, lifecycle, reactive state
+    arrow-js-obsidian-porting    sandbox→plugin parity check
+    obsidian-arrow-maintenance   updating an existing project
 
 ARROW v1.0.6 FOOTGUNS — do not relearn these the hard way:
 1. NO literal HTML comments inside html`` templates — Arrow treats HTML comments
@@ -68,8 +75,9 @@ CONVENTIONS
   only when Obsidian has no class, scoped under a container class + element type
   (e.g. `.my-panel button.my-action`) so it beats Obsidian's global button rule.
 - Sandbox-only chrome lives in src/sandbox/* — it does NOT port to a plugin.
-- Add a demo by exporting an Arrow component and registering it in
-  src/examples/registry.ts (it shows on the index and at its own route).
+- Add a demo by creating a co-located `*.stories.ts` next to the component (see
+  README "Add a story"); it appears at `/components/<slug>` automatically.
+  Browse Obsidian tokens/classes at `/reference`.
 
 VERIFY BEFORE CLAIMING DONE
 - `pnpm typecheck && pnpm test && pnpm lint` (or `pnpm run ci` for the full chain).
@@ -81,15 +89,18 @@ PORTING TO A PLUGIN
 Copy the component file into the plugin's view dir and mount from
 ItemView.onOpen() via `template(this.contentEl)`. If it uses boundary()/async
 components, add @arrow-js/framework to the plugin and the side-effect
-`import '@arrow-js/framework'`. Leave src/sandbox/* behind. Guard against drift
-with the porting-parity check (see the arrow-js-obsidian-porting skill).
+`import '@arrow-js/framework'`. Also copy src/utilities.css into the plugin once
+(all ported components share it) — components may use oas-* utility classes
+(flex, gap, padding, text, border helpers built on Obsidian's token scale).
+Leave src/sandbox/* behind. Guard against drift with the porting-parity check
+(see the arrow-js-obsidian-porting skill).
 
 MAINTENANCE (existing project)
 Refresh tooling later with `npx create-obsidian-arrow update` (preserves src/),
 update skills with `pnpm skills:update`. See the obsidian-arrow-maintenance skill.
 
 Start by scaffolding, running setup steps, then read AGENTS.md and confirm
-`pnpm dev` renders /example correctly. Report what you see.
+`pnpm dev` renders correctly at /components and /reference. Report what you see.
 ```
 
 ---

package/template/docs/prompts/update-existing.md

@@ -60,7 +60,7 @@ STEPS (in order)
 
 7. Verify
    - pnpm run ci          (biome + typecheck + tests + build)
-   - pnpm dev             and confirm /example renders with a clean console
+   - pnpm dev             and confirm /components and /reference render with a clean console
 
 REPORT
 - What `update` changed, which skills are now installed and where, the pull-css

package/template/docs/workflow.md

@@ -25,7 +25,8 @@ pnpm pull-css                            # macOS: auto-detects /Applications/Obs
                                          #        or  OBSIDIAN_ASAR=<path> pnpm pull-css
 
 # 4. Run it
-pnpm dev                                 # open the printed URL — / is the index, /example the demo
+pnpm dev                                 # open the printed URL — / is home, /components the story
+                                         # viewer, /reference the token/class index
 ```
 
 `public/app.css` is **git-ignored and never shipped** (it's Obsidian's proprietary
@@ -54,8 +55,15 @@ Then point the agent at [`AGENTS.md`](../AGENTS.md), or brief a fresh agent with
 ## Build → verify → port loop
 
 ```sh
-# add a component in src/components/, register it in src/examples/registry.ts
+# 1. Check /reference/classes in the running sandbox — does Obsidian have a class
+#    for your pattern? Use it before writing custom CSS.
+# 2. Add src/components/MyThing.ts (Arrow component)
+# 3. Add src/components/MyThing.stories.ts (co-located story file)
 pnpm dev          # iterate with HMR
+#    /components          → index of all discovered stories
+#    /components/my-thing → story for MyThing
+#    /reference           → live Obsidian token reference
+#    /reference/classes   → curated class catalog with live previews
 pnpm run ci       # biome + typecheck + tests + build before trusting it
 ```
 
@@ -63,10 +71,14 @@ Always confirm the actual render in the browser — Arrow's footguns surface onl
 at render, so a passing `tsc` is not proof a component works. See the footguns in
 [`AGENTS.md`](../AGENTS.md) and the `arrow-js-obsidian-templates` skill.
 
-**Port a component into a plugin:** copy the file into the plugin's view directory
-and mount it from `ItemView.onOpen()` via `template(this.contentEl)`. If it uses
-`boundary()`/async components, add `@arrow-js/framework` to the plugin and the
-side-effect `import '@arrow-js/framework'`. Leave `src/sandbox/*` behind.
+For the complete story authoring workflow (`defineStories` API, variants, children,
+status flag, DRY patterns) see the `obsidian-arrow-stories` skill.
+
+**Port a component into a plugin:** copy the component file and `src/utilities.css`
+(once, shared by all ports) into the plugin. Mount from `ItemView.onOpen()` via
+`template(this.contentEl)`. If it uses `boundary()`/async, add
+`@arrow-js/framework` and `import '@arrow-js/framework'`. Leave `src/sandbox/*`
+behind.
 
 ## Scaffold vs. clone
 

package/template/package.json

@@ -14,7 +14,7 @@
 		"create:sync": "node create-obsidian-arrow/scripts/sync-template.mjs",
 		"lint": "biome check .",
 		"format": "biome check --write .",
-		"test": "node --test test/*.test.mjs",
+		"test": "node --experimental-strip-types --test test/*.test.mjs",
 		"check": "biome check --write . && pnpm typecheck && pnpm test",
 		"ci": "biome ci . && pnpm typecheck && pnpm test && pnpm build",
 		"skills:install": "node scripts/install-skills.mjs --force",

package/template/src/components/SettingsPanel.stories.ts

@@ -0,0 +1,11 @@
+import { defineStories } from "../viewer/stories";
+import { SettingsPanel } from "./SettingsPanel";
+
+export default defineStories({
+	description: "Vertical tabs, toggles, a keyed list, and an async boundary() section.",
+	variants: {
+		default: () => SettingsPanel(),
+	},
+	children: ["toggle"],
+	status: "live",
+});

package/template/src/components/SettingsPanel.ts

@@ -70,7 +70,7 @@ function rebuildIndex(): void {
  * live state; clicking flips it in place (deep reactivity re-runs only the
  * tracked expressions below — no list re-render).
  */
-const Toggle = (enabled: () => boolean, onToggle: () => void): ArrowTemplate => html`<div
+export const Toggle = (enabled: () => boolean, onToggle: () => void): ArrowTemplate => html`<div
     class="${() => `checkbox-container${enabled() ? " is-enabled" : ""}`}"
     @click="${onToggle}"
   >

package/template/src/components/Toggle.stories.ts

@@ -0,0 +1,28 @@
+import { reactive } from "@arrow-js/core";
+import { defineStories } from "../viewer/stories";
+import { Toggle } from "./SettingsPanel";
+
+export default defineStories({
+	description: "Obsidian checkbox-container toggle used by SettingsPanel.",
+	componentPath: "src/components/SettingsPanel.ts",
+	variants: {
+		interactive: () => {
+			const state = reactive({ on: true });
+			return Toggle(
+				() => state.on,
+				() => {
+					state.on = !state.on;
+				}
+			);
+		},
+		off: {
+			render: () =>
+				Toggle(
+					() => false,
+					() => {}
+				),
+			notes: "Static off state (click does nothing).",
+		},
+	},
+	status: "live",
+});

package/template/src/main.ts

@@ -4,6 +4,7 @@ import "@arrow-js/framework";
 
 import { startRouter } from "./router/client";
 import { applyTheme } from "./sandbox/theme";
+import "./utilities.css";
 import "./sandbox/sandbox.css";
 
 applyTheme();

package/template/src/router/client.ts

@@ -1,5 +1,7 @@
+import { html } from "@arrow-js/core";
 import { Frame } from "../sandbox/frame";
 import { Shell } from "../sandbox/shell";
+import type { Page } from "./routeToPage";
 import { routeToPage } from "./routeToPage";
 
 /**
@@ -29,10 +31,21 @@ function getNavigation(): NavigationLike | undefined {
 
 export function startRouter(root: HTMLElement): void {
 	const render = (url: string): void => {
-		const page = routeToPage(url);
+		let resolved = routeToPage(url);
+		for (let hops = 0; "redirect" in resolved && hops < 3; hops++) {
+			window.history.replaceState({}, "", resolved.redirect);
+			resolved = routeToPage(resolved.redirect);
+		}
+		if ("redirect" in resolved) {
+			return;
+		}
+		const page: Page = resolved;
 		document.title = page.title;
 		root.replaceChildren();
-		Shell(Frame(page.title, page.view))(root);
+		const content = page.sidebar
+			? html`${page.sidebar}${Frame(page.title, page.view)}`
+			: Frame(page.title, page.view);
+		Shell(content)(root);
 	};
 
 	render(window.location.href);

package/template/src/router/routeToPage.ts

@@ -1,43 +1,33 @@
 import { html } from "@arrow-js/core";
 import type { ArrowExpression } from "@arrow-js/core";
-import { findExample } from "../examples/registry";
 import { Home } from "../sandbox/home";
+import { ClassesPage } from "../viewer/ClassesPage";
+import { ComponentsIndex } from "../viewer/ComponentsIndex";
+import { StoryPage } from "../viewer/StoryPage";
+import { TokensPage } from "../viewer/TokensPage";
+import { findStory } from "../viewer/discovery";
+import { ViewerSidebar } from "../viewer/sidebar";
 
 /**
- * Single route resolver, shared by every entry point. Returns the page status,
- * title (metadata), and Arrow view together — the same shape the Arrow Vite
- * scaffold uses, so a future SSR/hydration lane can call this identically on
- * both server and client. The client router (./client.ts) wraps the view in the
- * sandbox Frame and sets document.title from this.
+ * Single route resolver, shared by every entry point (Arrow scaffold shape, so
+ * a future SSR lane could call it identically). Pages may carry a sidebar
+ * (rendered outside the pane) and routes may resolve to a redirect, which the
+ * client router applies via history.replaceState.
  */
 export interface Page {
 	status: number;
 	title: string;
 	view: ArrowExpression;
+	sidebar?: ArrowExpression;
 }
 
-const APP_NAME = "Arrow Sandbox";
-
-export function routeToPage(url: string): Page {
-	const { pathname } = new URL(url, window.location.origin);
-
-	if (pathname === "/" || pathname === "") {
-		return {
-			status: 200,
-			title: APP_NAME,
-			view: Home(),
-		};
-	}
+export interface Redirect {
+	redirect: string;
+}
 
-	const match = findExample(pathname);
-	if (match) {
-		return {
-			status: 200,
-			title: `${match.label} · ${APP_NAME}`,
-			view: match.view(),
-		};
-	}
+const APP_NAME = "Arrow Sandbox";
 
+function notFound(pathname: string): Page {
 	return {
 		status: 404,
 		title: `Not found · ${APP_NAME}`,
@@ -47,7 +37,7 @@ export function routeToPage(url: string): Page {
 					<div class="setting-item-info">
 						<div class="setting-item-name">Not found</div>
 						<div class="setting-item-description">
-							No route for <code>${pathname}</code>. <a href="/">Back to examples</a>.
+							No route for <code>${pathname}</code>. <a href="/">Back home</a>.
 						</div>
 					</div>
 				</div>
@@ -55,3 +45,60 @@ export function routeToPage(url: string): Page {
 		`,
 	};
 }
+
+export function routeToPage(url: string): Page | Redirect {
+	const { pathname, searchParams } = new URL(url, window.location.origin);
+
+	if (pathname === "/" || pathname === "") {
+		return { status: 200, title: APP_NAME, view: Home() };
+	}
+
+	if (pathname === "/example") {
+		return { redirect: "/components/settings-panel" };
+	}
+
+	if (pathname === "/components" || pathname === "/components/") {
+		return {
+			status: 200,
+			title: `Components · ${APP_NAME}`,
+			view: ComponentsIndex(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	const storyMatch = pathname.match(/^\/components\/([^/]+)$/);
+	if (storyMatch) {
+		const story = findStory(storyMatch[1]);
+		if (!story) {
+			return { ...notFound(pathname), sidebar: ViewerSidebar(pathname) };
+		}
+		const requested = searchParams.get("variant");
+		const variantName = requested ?? Object.keys(story.variants)[0];
+		return {
+			status: story.variants[variantName] ? 200 : 404,
+			title: `${story.title} · ${APP_NAME}`,
+			view: StoryPage(story, variantName),
+			sidebar: ViewerSidebar(`/components/${story.slug}`),
+		};
+	}
+
+	if (pathname === "/reference") {
+		return {
+			status: 200,
+			title: `Tokens · ${APP_NAME}`,
+			view: TokensPage(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	if (pathname === "/reference/classes") {
+		return {
+			status: 200,
+			title: `Classes · ${APP_NAME}`,
+			view: ClassesPage(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	return notFound(pathname);
+}

package/template/src/sandbox/home.ts

@@ -1,22 +1,12 @@
 import { component, html, reactive } from "@arrow-js/core";
 import type { ArrowTemplate } from "@arrow-js/core";
-import { ExamplesIndex } from "../examples/ExamplesIndex";
-import { examples } from "../examples/registry";
 import { layoutState } from "./layout";
 import { themeState } from "./theme";
 
-/**
- * Sandbox landing page at "/": a readiness check + getting-started commands +
- * the examples list. Sandbox chrome — does not port to a plugin.
- *
- * The readiness probe catches the #1 fresh-machine gotcha: running `pnpm dev`
- * before `pnpm pull-css` leaves app.css unloaded, so every `var(--…)` token is
- * empty. We detect that by reading the computed value of a known token.
- */
 const probe = reactive({ tick: 0 });
 
 function stylingLoaded(): boolean {
-	const generation = probe.tick; // reactive dependency; Re-check bumps it
+	const generation = probe.tick;
 	const style = getComputedStyle(document.body);
 	return (
 		generation >= 0 &&
@@ -29,6 +19,8 @@ function recheck(): void {
 	probe.tick++;
 }
 
+const gettingStarted = reactive({ expanded: false });
+
 const GETTING_STARTED = [
 	{ cmd: "pnpm pull-css", note: "extract Obsidian's app.css — run once (macOS auto-detect)" },
 	{ cmd: "pnpm dev", note: "this dev server (Vite + HMR)" },
@@ -36,9 +28,13 @@ const GETTING_STARTED = [
 	{ cmd: "pnpm run ci", note: "biome + typecheck + tests + build" },
 ];
 
+const VIEWS = [
+	{ label: "Components", path: "/components", note: "Component story viewer" },
+	{ label: "Tokens", path: "/reference", note: "CSS custom property reference" },
+	{ label: "Classes", path: "/reference/classes", note: "Obsidian class catalog" },
+];
+
 export const Home = component((): ArrowTemplate => {
-	// Re-probe shortly after mount, in case app.css finished loading after the
-	// first paint (stylesheets load async).
 	setTimeout(recheck, 250);
 
 	return html`
@@ -79,28 +75,61 @@ export const Home = component((): ArrowTemplate => {
 					</div>
 				</div>
 			</div>
+		</div>
 
+		<div class="${() => (gettingStarted.expanded ? "oas-card is-expanded" : "oas-card")}">
+			<div
+				class="oas-card-header"
+				@click="${() => {
+					gettingStarted.expanded = !gettingStarted.expanded;
+				}}"
+			>
+				<span class="oas-card-title">Getting started</span>
+				<span class="oas-card-chevron">›</span>
+			</div>
+			<div class="oas-card-body">
+				<div class="oas-settings">
+					${GETTING_STARTED.map((step) =>
+						html`
+							<div class="setting-item">
+								<div class="setting-item-info">
+									<div class="setting-item-name" style="font-family: var(--font-monospace);">
+										${step.cmd}
+									</div>
+									<div class="setting-item-description">${step.note}</div>
+								</div>
+							</div>
+						`.key(step.cmd)
+					)}
+				</div>
+				<p class="oas-card-note">
+					See AGENTS.md + docs/ for the full flow; agent prompts in docs/prompts/.
+				</p>
+			</div>
+		</div>
+
+		<div class="oas-settings">
 			<div class="setting-item setting-item-heading">
 				<div class="setting-item-info">
-					<div class="setting-item-name">Getting started</div>
-					<div class="setting-item-description">
-						See AGENTS.md + docs/ for the full flow; agent prompts in docs/prompts/.
-					</div>
+					<div class="setting-item-name">Views</div>
+					<div class="setting-item-description">Main pages in this sandbox.</div>
 				</div>
 			</div>
-			${GETTING_STARTED.map((step) =>
+			${VIEWS.map((view) =>
 				html`
-						<div class="setting-item">
-							<div class="setting-item-info">
-								<div class="setting-item-name" style="font-family: var(--font-monospace);">
-									${step.cmd}
-								</div>
-								<div class="setting-item-description">${step.note}</div>
+					<div class="setting-item">
+						<div class="setting-item-info">
+							<div class="setting-item-name">
+								<a href="${view.path}">${view.label}</a>
 							</div>
+							<div class="setting-item-description">${view.note}</div>
 						</div>
-					`.key(step.cmd)
+						<div class="setting-item-control">
+							<a class="mod-cta oas-open-link" href="${view.path}">Open</a>
+						</div>
+					</div>
+				`.key(view.label)
 			)}
 		</div>
-		${ExamplesIndex(examples)}
 	`;
 });