@noobsociety/nsds 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# NoobSociety Design System
+
+**NSDS** is the reusable NoobSociety Design System package: design tokens, CSS primitives, React components, MUI theme source, pixel assets, and reference UI kits for building NoobSociety interfaces.
+
+The system is built around a simple rule: **Monokai colors are semantic foregrounds, dark surfaces are the world canvas.**
+
+## Install
+
+Install from npm after publish:
+
+```bash
+npm install @noobsociety/nsds
+```
+
+Use a local workspace package before publish:
+
+```json
+{
+  "dependencies": {
+    "@noobsociety/nsds": "file:../design-system"
+  }
+}
+```
+
+## Usage
+
+Import the full CSS entry when you want tokens, base styles, and shared primitives:
+
+```js
+import '@noobsociety/nsds/styles.css';
+```
+
+Use React components with the CSS entry:
+
+```jsx
+import '@noobsociety/nsds/styles.css';
+import { Button, FeatureCard, QuestCard, SectionArrow } from '@noobsociety/nsds/react';
+
+export function Example() {
+  return (
+    <Button href="https://noobsociety.com">▶ Enter the world</Button>
+  );
+}
+```
+
+Use individual token or asset files when a project only needs part of the system:
+
+```js
+import '@noobsociety/nsds/tokens/colors.css';
+import logoUrl from '@noobsociety/nsds/assets/logo.png';
+```
+
+Use the MUI theme in TypeScript-aware app bundlers:
+
+```ts
+import { NSThemeProvider, theme, NS } from '@noobsociety/nsds/mui';
+```
+
+The MUI entry currently exports source TypeScript. Add a build step before publishing to consumers that require plain JavaScript MUI runtime files.
+
+## Package Exports
+
+| Export | Purpose |
+|---|---|
+| `@noobsociety/nsds` | Root React component entry |
+| `@noobsociety/nsds/react` | React components |
+| `@noobsociety/nsds/mui` | MUI theme source |
+| `@noobsociety/nsds/styles.css` | Full CSS entry |
+| `@noobsociety/nsds/package.json` | Package metadata |
+| `@noobsociety/nsds/components/primitives.css` | Component primitive classes only |
+| `@noobsociety/nsds/tokens/*` | Individual token CSS files |
+| `@noobsociety/nsds/assets/*` | Pixel assets and brand images |
+| `@noobsociety/nsds/guidelines/*` | Specimen cards |
+| `@noobsociety/nsds/references/*` | Polished `.dc.html` references |
+| `@noobsociety/nsds/ui-kits/*` | Complete UI kits |
+
+## Design Model
+
+### Monokai Foregrounds
+
+Monokai colors are used on top of the canvas: text, icons, borders, buttons, status pills, accents, and interaction states. Each hue has one semantic role. Do not reassign a color to a different role.
+
+| Token | Hex | Role |
+|---|---|---|
+| `--ns-ink` | `#f8f8f2` | Primary text |
+| `--ns-ink-faint` | `#75715e` | Muted text, captions, placeholders |
+| `--ns-gold` | `#e6db74` | Primary accent, CTAs, eyebrows, active nav |
+| `--ns-green` | `#a6e22e` | Success, live state, `HOLDS` |
+| `--ns-orange` | `#fd971f` | In progress, active state, `BUILDING` |
+| `--ns-cyan` | `#66d9e8` | Planned, info, links |
+| `--ns-pink` | `#f92672` | Highlight, danger, high-energy accent |
+| `--ns-purple` | `#ae81ff` | Decorative, personal, tertiary accent |
+
+### Dark Canvas
+
+Dark colors sit underneath the Monokai foregrounds. They define the world canvas, raised surfaces, headers, cards, and overlays.
+
+| Token | Hex | Role |
+|---|---|---|
+| `--ns-bg-0` | `#1a1a16` | Deepest surface: footer, sidebar, backdrop |
+| `--ns-bg-1` | `#272822` | Page base |
+| `--ns-bg-2` | `#32332b` | Raised surface, icon slot, input fill |
+| `--ns-glass` | `rgba(30,31,26,.88)` | Card and header glass |
+
+The default experience is dark. Do not introduce a light-mode default unless it is intentionally designed as a separate theme.
+
+## Content Rules
+
+- **Voice:** Direct, honest, playful. Not corporate.
+- **Casing:** Sentence case. Title case only for names and proper nouns.
+- **Length:** Short sentences. One idea per sentence.
+- **Emoji:** Avoid emoji. Use pixel accents such as `✦`, `▶`, `★`, `✓`, and `◌` when useful.
+- **Numbers:** Use numbers only when they are specific and meaningful.
+- **Perspective:** Speak directly. Avoid abstract phrases like "users" and "visitors" when "you" is clearer.
+
+## Visual Rules
+
+### Typography
+
+- `Press Start 2P`: wordmark, buttons, status pills, card labels, section accents, and pixel UI.
+- `Inter`: body copy, navigation, subtitles, paragraphs, and dense information.
+- Pixel text must use generous line height. Keep it short.
+- Body copy should stay readable and calm.
+
+### Layout
+
+- Base spacing follows a 4px grid.
+- Default container width is `1080px`.
+- Full sections use `min-height: calc(100svh - var(--ns-header-h))`.
+- Responsive baseline: `375x667` portrait and `667x375` landscape.
+
+### Cards
+
+- Use glass surfaces with `10px` radius.
+- Do not add resting drop shadows.
+- Use hover elevation only: `translateY(-4px)` plus the card hover shadow.
+
+### Buttons
+
+- Primary `play` buttons use gold fill, dark text, a gold border, and a physical press shadow.
+- `ghost` buttons stay transparent until hover.
+- Buttons use `Press Start 2P`.
+
+### Motion
+
+- Keep interaction motion fast: `150ms ease-out`.
+- Keep decorative motion subtle.
+- Respect reduced motion; `ns-*` animations are disabled under `prefers-reduced-motion: reduce`.
+
+## Component Notes
+
+### Button
+
+Use for primary and secondary actions.
+
+```jsx
+<Button variant="play" href="https://noobsociety.com">▶ Enter the world</Button>
+<Button variant="ghost" href="https://github.com/noobsociety">★ Star on GitHub</Button>
+<Button variant="play" size="sm">▶ Play</Button>
+```
+
+### FeatureCard
+
+Use for short feature grids. Render inside a `ul`.
+
+```jsx
+<FeatureCard
+  icon={<CursorIcon />}
+  title="The site is a world"
+  body="Pages are maps, links are interactables."
+  tag="Spatial"
+/>
+```
+
+### QuestCard
+
+Use for gate or roadmap states. Render inside an `ol`.
+
+```jsx
+<QuestCard
+  gate={3}
+  title="Objects"
+  body="In-space sections open content."
+  status="active"
+/>
+```
+
+Status mapping:
+
+| Status | Label | Color |
+|---|---|---|
+| `done` | `HOLDS` | `--ns-green` |
+| `active` | `BUILDING` | `--ns-orange` |
+| `planned` | `PLANNED` | `--ns-cyan` |
+| `locked` | `LATER` | `--ns-ink-faint` |
+
+## File Index
+
+| Path | Contents |
+|---|---|
+| `package.json` | Package metadata, exports, peer dependencies |
+| `index.js` / `index.d.ts` | Root React component entry point |
+| `styles.css` | Global CSS entry point |
+| `support.js` | Runtime support for root `.dc.html` references |
+| `tokens/` | Color, typography, spacing, motion, and base CSS tokens |
+| `components/primitives.css` | Shared CSS primitives |
+| `components/react/` | Public React component barrel export |
+| `components/buttons/` | Button component, types, prompt, specimen |
+| `components/cards/` | FeatureCard and QuestCard components, types, prompts, specimens |
+| `components/navigation/` | SectionArrow component, types, specimen |
+| `mui-theme/` | MUI theme source and examples |
+| `assets/` | Logo, sprites, and world imagery |
+| `guidelines/` | Visual specimen cards |
+| `references/` | Polished `.dc.html` references |
+| `ui-kits/` | Complete UI kits |
+| `SKILL.md` | Agent skill definition |
+
+## Package Status
+
+The current package is ready for local reuse and npm publication as `@noobsociety/nsds@0.1.0`. Before broad public adoption, add a repository URL and choose a license.

package/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: noobsociety-design
+description: Use this skill to design and implement NoobSociety interfaces with the NSDS package, including design tokens, CSS primitives, React components, MUI theme source, pixel assets, and reference UI kits.
+user-invocable: true
+---
+
+Read `README.md` first, then inspect the relevant tokens, components, assets, guidelines, references, or UI kits for the task.
+
+If creating visual artifacts such as mockups, slides, or prototypes, use the included assets and produce static HTML the user can open. If working in production code, import the package entry points and follow the documented token and component rules.
+
+**Core principles:**
+1. Monokai colors are semantic foregrounds: text, icons, accents, buttons, borders, and status colors.
+2. Dark surfaces are the world canvas: page base, raised surfaces, glass overlays, cards, headers, and footers.
+3. Never reassign a Monokai color to a different semantic role.
+4. The default experience is dark. Do not introduce light mode as the default.
+5. Keep copy direct, short, and playful without becoming corporate.
+
+When the user does not specify an output format, choose the most useful one: static HTML for visual artifacts, package imports for production code, or concise design guidance for review and planning.

package/components/buttons/Button.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @startingPoint section="Components" subtitle="Play and Ghost button variants" viewport="700x180"
+ */
+import type * as React from 'react';
+
+export interface ButtonProps {
+  /** Visual style */
+  variant?: 'play' | 'ghost';
+  /** Size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Render as <a> when provided */
+  href?: string;
+  onClick?: React.MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;
+  children?: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  type?: 'button' | 'submit' | 'reset';
+}
+
+export declare function Button(props: ButtonProps): React.ReactElement;

package/components/buttons/Button.js

@@ -0,0 +1,55 @@
+import React from 'react';
+
+import { cx } from '../shared/styles.js';
+
+const VALID_VARIANTS = new Set(['play', 'ghost']);
+const VALID_SIZES = new Set(['sm', 'md', 'lg']);
+
+export function Button({
+  variant = 'play',
+  size = 'md',
+  href,
+  onClick,
+  children,
+  disabled = false,
+  className,
+  type = 'button',
+  ...props
+}) {
+  const resolvedVariant = VALID_VARIANTS.has(variant) ? variant : 'play';
+  const resolvedSize = VALID_SIZES.has(size) ? size : 'md';
+  const classes = cx(
+    'ns-button',
+    `ns-button--${resolvedVariant}`,
+    `ns-button--${resolvedSize}`,
+    className,
+  );
+  const commonProps = {
+    ...props,
+    className: classes,
+    onClick: disabled ? undefined : onClick,
+  };
+
+  if (href) {
+    return React.createElement(
+      'a',
+      {
+        ...commonProps,
+        href: disabled ? undefined : href,
+        'aria-disabled': disabled || undefined,
+        tabIndex: disabled ? -1 : props.tabIndex,
+      },
+      children,
+    );
+  }
+
+  return React.createElement(
+    'button',
+    {
+      ...commonProps,
+      type,
+      disabled,
+    },
+    children,
+  );
+}

package/components/buttons/Button.prompt.md

@@ -0,0 +1,22 @@
+Use `Button` for primary and secondary actions in NoobSociety interfaces.
+
+```jsx
+<Button variant="play" href="https://noobsociety.com">▶ Enter the world</Button>
+<Button variant="ghost" href="https://github.com/noobsociety">★ Star on GitHub</Button>
+<Button variant="play" size="sm">▶ Play</Button>
+```
+
+**Variants**
+- `play` — primary CTA. Gold fill, dark text, gold border, physical press shadow.
+- `ghost` — secondary CTA. Transparent surface, gold text, soft border, gold fill on hover.
+
+**Sizes**
+- `sm` — compact header actions
+- `md` — default actions
+- `lg` — hero and major CTA sections
+
+**Notes**
+- Always uses Press Start 2P — never Inter.
+- Pass `href` to render as `<a>`. Omit for `<button>`.
+- Import `styles.css` so the `ns-button` primitive classes are available.
+- Use a short pixel symbol prefix such as `▶` or `★` when it clarifies the action.

package/components/buttons/buttons.card.html

@@ -0,0 +1,24 @@
+<!-- @dsCard group="Components" viewport="700x200" name="Button" subtitle="Play (primary) and Ghost (secondary) — SVG icons, fluid padding" -->
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="../../styles.css">
+<style>
+  body { background: var(--ns-bg-1); padding: 1.75rem 2rem; display: flex; flex-direction: column; gap: 1.5rem; }
+  .row { display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: center; }
+  .label { font-family: var(--ns-font-pixel); font-size: 7px; color: var(--ns-ink-faint); min-width: 3.75rem; }
+</style>
+</head>
+<body>
+<div class="row">
+  <span class="label">Play</span>
+  <a class="ns-button ns-button--play ns-button--md" href="#"><svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor" aria-hidden="true"><polygon points="1,0.5 9.5,5 1,9.5"/></svg>Enter the world</a>
+  <a class="ns-button ns-button--play ns-button--sm" href="#"><svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor" aria-hidden="true"><polygon points="1,0.5 9.5,5 1,9.5"/></svg>Play</a>
+</div>
+<div class="row">
+  <span class="label">Ghost</span>
+  <a class="ns-button ns-button--ghost ns-button--md" href="#"><svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor" aria-hidden="true"><polygon points="5,0.5 6.2,3.8 9.8,3.8 6.9,5.9 8,9.2 5,7.1 2,9.2 3.1,5.9 0.2,3.8 3.8,3.8"/></svg>Star on GitHub</a>
+</div>
+</body>
+</html>

package/components/cards/FeatureCard.d.ts

@@ -0,0 +1,18 @@
+import type * as React from 'react';
+
+export interface FeatureCardProps {
+  /** Pixel-art icon element */
+  icon: React.ReactNode;
+  /** Card heading — Press Start 2P */
+  title: string;
+  /** Body copy — Inter 14px */
+  body: string;
+  /** Small tag label in top-right (e.g. "Spatial", "Live") */
+  tag?: string;
+  /** Icon color — defaults to gold #e6db74 */
+  iconColor?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export declare function FeatureCard(props: FeatureCardProps): React.ReactElement;

package/components/cards/FeatureCard.js

@@ -0,0 +1,36 @@
+import React from 'react';
+
+import { NS, cx, mergeStyles } from '../shared/styles.js';
+
+export function FeatureCard({
+  icon,
+  title,
+  body,
+  tag,
+  iconColor = NS.gold,
+  className,
+  style,
+  ...props
+}) {
+  return React.createElement('li', {
+    ...props,
+    className: cx('ns-card ns-feature-card', className),
+    style: mergeStyles({ '--ns-feature-accent': iconColor }, style),
+  },
+    React.createElement('span', {
+      className: 'ns-icon-slot ns-feature-card__icon',
+      'aria-hidden': true,
+    }, icon),
+    React.createElement('div', null,
+      React.createElement('h3', {
+        className: 'ns-feature-card__title',
+      }, title),
+      React.createElement('p', {
+        className: 'ns-feature-card__body',
+      }, body),
+    ),
+    tag && React.createElement('span', {
+      className: 'ns-tag ns-feature-card__tag',
+    }, tag),
+  );
+}

package/components/cards/FeatureCard.prompt.md

@@ -0,0 +1,17 @@
+Use `FeatureCard` for short feature grids and value propositions. Render cards inside a `ul`.
+
+```jsx
+<ul style={{ display:'grid', gridTemplateColumns:'repeat(4,1fr)', gap:14, listStyle:'none', margin:0, padding:0 }}>
+  <FeatureCard icon={<CursorIcon/>} title="The site is a world" body="Pages are maps, links are interactables." tag="Spatial" />
+  <FeatureCard icon={<BoltIcon/>}   title="One typed bridge"   body="A map object in Phaser fires the matching React overlay." tag="Live" iconColor="var(--ns-pink)" />
+  <FeatureCard icon={<BubbleIcon/>} title="Sprite-forward"     body="Clear silhouettes, readable at a glance." tag="Personal" iconColor="var(--ns-purple)" />
+  <FeatureCard icon={<BookIcon/>}   title="Built in the open"  body="CI on every push. Cloudflare Pages deploy." tag="Open" iconColor="var(--ns-cyan)" />
+</ul>
+```
+
+**Notes**
+- Keep titles short. Pixel headings lose clarity when they wrap too often.
+- `iconColor` should use a semantic Monokai token: gold by default, or pink, purple, or cyan when the meaning fits.
+- Import `styles.css` so the `ns-card`, `ns-feature-card`, and `ns-tag` classes are available.
+- Keep `tag` to one short word.
+- Hover: `translateY(-4px)` + gold border glow.

package/components/cards/QuestCard.d.ts

@@ -0,0 +1,16 @@
+import type * as React from 'react';
+
+export interface QuestCardProps {
+  /** Gate number shown in the title */
+  gate: number;
+  /** Short gate name (e.g. "Space", "Movement") */
+  title: string;
+  /** One-sentence description */
+  body: string;
+  /** Controls border color, bg tint, icon, and pill label */
+  status?: 'done' | 'active' | 'planned' | 'locked';
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export declare function QuestCard(props: QuestCardProps): React.ReactElement;

package/components/cards/QuestCard.js

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import { cx, questStatus } from '../shared/styles.js';
+
+export function QuestCard({ gate, title, body, status = 'locked', className, ...props }) {
+  const s = questStatus[status] || questStatus.locked;
+  return React.createElement('li', {
+    ...props,
+    className: cx('ns-quest-card', s.className, className),
+  },
+    React.createElement('span', {
+      className: 'ns-quest-card__icon',
+      'aria-hidden': true,
+    }, s.icon),
+    React.createElement('div', { className: 'ns-quest-card__body' },
+      React.createElement('p', {
+        className: 'ns-quest-card__title',
+      }, `Gate ${gate} · ${title}`),
+      React.createElement('p', {
+        className: 'ns-quest-card__desc',
+      }, body),
+      React.createElement('span', {
+        className: 'ns-status-pill',
+      }, s.label),
+    ),
+  );
+}

package/components/cards/QuestCard.prompt.md

@@ -0,0 +1,19 @@
+Use `QuestCard` for roadmap gates, progress checkpoints, and locked future work. Render cards inside an `ol`.
+
+```jsx
+<ol style={{ display:'grid', gridTemplateColumns:'repeat(3,1fr)', gap:11, listStyle:'none', margin:0, padding:0 }}>
+  <QuestCard gate={1} title="Space"     body="Walkable area exists."            status="done"    />
+  <QuestCard gate={2} title="Movement"  body="Movement feels right."            status="done"    />
+  <QuestCard gate={3} title="Objects"   body="In-space sections open content."  status="active"  />
+  <QuestCard gate={6} title="Identity"  body="Space and character read as one." status="planned" />
+  <QuestCard gate={8} title="Combat"    body="Unlocks after single-player loop." status="locked"  />
+</ol>
+```
+
+**Status mapping**
+- `done` → `HOLDS`, green `#a6e22e`
+- `active` → `BUILDING`, orange `#fd971f`
+- `planned` → `PLANNED`, cyan `#66d9e8`
+- `locked` → `LATER`, faint `#75715e`, reduced opacity
+
+Import `styles.css` so the `ns-quest-card` and `ns-status-pill` classes are available.

package/components/cards/cards.card.html

@@ -0,0 +1,54 @@
+<!-- @dsCard group="Components" viewport="700x380" name="Cards" subtitle="FeatureCard (semantic colors) and QuestCard (status system)" -->
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="../../styles.css">
+<style>
+  body { background: var(--ns-bg-1); padding: 1.5rem 1.75rem; display: flex; flex-direction: column; gap: 1.25rem; }
+  .label { font-family: var(--ns-font-pixel); font-size: 7px; color: var(--ns-ink-faint); margin: 0 0 0.625rem; }
+  .grid-4 { display: grid; grid-template-columns: repeat(4, minmax(0,1fr)); gap: 0.875rem; list-style: none; margin: 0; padding: 0; }
+  .grid-3 { display: grid; grid-template-columns: repeat(3, minmax(0,1fr)); gap: 0.875rem; list-style: none; margin: 0; padding: 0; }
+</style>
+</head>
+<body>
+<p class="label">Feature cards — icon colors are Monokai semantic</p>
+<ul class="grid-4">
+  <li class="ns-card ns-feature-card">
+    <div class="ns-icon-slot ns-feature-card__icon"><svg viewBox="0 0 24 24" width="26" height="26" fill="currentColor" aria-hidden="true"><path d="M5 2.6 L5 18.6 L9.2 14.7 L12 20.8 L14.4 19.6 L11.6 13.7 L17.4 13.7 Z"/></svg></div>
+    <div><p class="ns-feature-card__title">The site is a world</p><p class="ns-feature-card__body">Pages are maps, links are interactables.</p></div>
+    <span class="ns-tag ns-feature-card__tag">Spatial</span>
+  </li>
+  <li class="ns-card ns-feature-card" style="--ns-feature-accent: var(--ns-pink)">
+    <div class="ns-icon-slot ns-feature-card__icon"><svg viewBox="0 0 24 24" width="26" height="26" fill="currentColor" aria-hidden="true"><path d="M13 2.5 L5 13.6 H11 L10.2 21.5 L19 9.4 H12.4 Z"/></svg></div>
+    <div><p class="ns-feature-card__title">One typed bridge</p><p class="ns-feature-card__body">Phaser fires the matching React overlay.</p></div>
+    <span class="ns-tag ns-feature-card__tag">Live</span>
+  </li>
+  <li class="ns-card ns-feature-card" style="--ns-feature-accent: var(--ns-purple)">
+    <div class="ns-icon-slot ns-feature-card__icon"><svg viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="M12 3.5 C6.9 3.5 3 7.1 3 11.7 C3 15.1 5.5 17.2 8.3 17.2 C9.9 17.2 10.4 16 11.7 16 C12.8 16 13.1 17.3 14.7 17.3 C18 17.3 21 14.7 21 11.1 C21 6.8 17 3.5 12 3.5 Z" stroke-linejoin="round"/><circle cx="8" cy="9" r="1.1" fill="currentColor" stroke="none"/><circle cx="12" cy="7.4" r="1.1" fill="currentColor" stroke="none"/><circle cx="16" cy="9" r="1.1" fill="currentColor" stroke="none"/></svg></div>
+    <div><p class="ns-feature-card__title">Sprite-forward</p><p class="ns-feature-card__body">Clear silhouettes, readable at a glance.</p></div>
+    <span class="ns-tag ns-feature-card__tag">Personal</span>
+  </li>
+  <li class="ns-card ns-feature-card" style="--ns-feature-accent: var(--ns-cyan)">
+    <div class="ns-icon-slot ns-feature-card__icon"><svg viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round" aria-hidden="true"><path d="M12 6.5 C9.5 4.9 6 4.6 3.6 5.5 V18.7 C6 17.8 9.5 18.1 12 19.8 C14.5 18.1 18 17.8 20.4 18.7 V5.5 C18 4.6 14.5 4.9 12 6.5 Z"/><path d="M12 6.5 V19.8"/></svg></div>
+    <div><p class="ns-feature-card__title">Built in the open</p><p class="ns-feature-card__body">CI on every push. Cloudflare Pages deploy.</p></div>
+    <span class="ns-tag ns-feature-card__tag">Open</span>
+  </li>
+</ul>
+<p class="label">Quest cards — status → Monokai color</p>
+<ul class="grid-3">
+  <li class="ns-quest-card ns-quest-card--done">
+    <span class="ns-quest-card__icon" aria-hidden="true">✓</span>
+    <div class="ns-quest-card__body"><p class="ns-quest-card__title">Gate 1 · Space</p><p class="ns-quest-card__desc">Walkable area exists.</p><span class="ns-status-pill">HOLDS</span></div>
+  </li>
+  <li class="ns-quest-card ns-quest-card--active">
+    <span class="ns-quest-card__icon" aria-hidden="true"><svg viewBox="0 0 10 10" width="8" height="8" fill="currentColor"><polygon points="1,0.5 9.5,5 1,9.5"/></svg></span>
+    <div class="ns-quest-card__body"><p class="ns-quest-card__title">Gate 3 · Objects</p><p class="ns-quest-card__desc">In-space sections open content.</p><span class="ns-status-pill">BUILDING</span></div>
+  </li>
+  <li class="ns-quest-card ns-quest-card--planned">
+    <span class="ns-quest-card__icon" aria-hidden="true">◌</span>
+    <div class="ns-quest-card__body"><p class="ns-quest-card__title">Gate 6 · Identity</p><p class="ns-quest-card__desc">Space and character read as one.</p><span class="ns-status-pill">PLANNED</span></div>
+  </li>
+</ul>
+</body>
+</html>

package/components/navigation/SectionArrow.d.ts

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+
+export interface SectionArrowProps {
+  /** href of the next section (e.g. "#why") */
+  href: string;
+  /** Accessible label for screen readers */
+  label: string;
+  children?: React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export declare function SectionArrow(props: SectionArrowProps): React.ReactElement;

package/components/navigation/SectionArrow.js

@@ -0,0 +1,28 @@
+import React from 'react';
+
+import { cx } from '../shared/styles.js';
+
+function ChevronDownIcon() {
+  return React.createElement('svg', {
+    viewBox: '0 0 12 8',
+    width: 12,
+    height: 12,
+    'aria-hidden': true,
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round',
+  },
+    React.createElement('polyline', { points: '1,1.5 6,6.5 11,1.5' }),
+  );
+}
+
+export function SectionArrow({ href, label, className, children, ...props }) {
+  return React.createElement('a', {
+    ...props,
+    href,
+    'aria-label': label,
+    className: cx('ns-section-arrow', className),
+  }, children || React.createElement(ChevronDownIcon));
+}

package/components/navigation/navigation.card.html

@@ -0,0 +1,29 @@
+<!-- @dsCard group="Components" viewport="700x120" name="Navigation" subtitle="SiteNav header with scroll-spy + SVG section arrow" -->
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<link rel="stylesheet" href="../../styles.css">
+<style>
+  body { background: var(--ns-bg-1); padding: 0; display: flex; flex-direction: column; }
+  .arrow-demo { position:relative; height:3.5rem; background:rgba(30,31,26,.3); }
+  .arrow-demo .ns-section-arrow { bottom:0.75rem; }
+  .nav-play { margin-left:2rem; }
+</style>
+</head>
+<body>
+  <nav class="ns-site-nav">
+    <a class="ns-brand" href="#"><img src="../../assets/logo.png" alt=""><span class="ns-brand__text">Noob<b class="ns-brand__accent">Society</b></span></a>
+    <ul class="ns-nav-links">
+      <li><a href="#">Why</a></li>
+      <li><a href="#" aria-current="page">World</a></li>
+      <li><a href="#">Roadmap</a></li>
+      <li><a href="#">Devblog</a></li>
+    </ul>
+    <a class="ns-button ns-button--play ns-button--sm nav-play" href="#"><svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor" aria-hidden="true"><polygon points="1,0.5 9.5,5 1,9.5"/></svg>Play</a>
+  </nav>
+  <div class="arrow-demo">
+    <a class="ns-section-arrow" href="#" aria-label="Go to next section"><svg viewBox="0 0 12 8" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="1,1.5 6,6.5 11,1.5"/></svg></a>
+  </div>
+</body>
+</html>