lanre-ds 0.0.0-stage → 0.2.0

package/components/effects/Sunburst.jsx

@@ -0,0 +1,26 @@
+'use client';
+import React, { useId } from 'react';
+
+/* Slow rays of light behind a focal point. It is SVG, so place it inside an <svg>, before the content it sits behind.
+   motion: 'continuous' turns for ever, 'once' fades in and out, 'still' stays put. Reduced motion stops it. */
+export function Sunburst({ x = 0, y = 0, radius = 500, rays = 12, color = '#ffe8ac', opacity = 0.13, duration = 120, motion = 'continuous' }) {
+  const id = 'sunburst-' + useId().replace(/:/g, '');
+  const count = Math.max(3, Math.min(24, Math.round(rays)));
+  const half = Math.PI / count * 0.42;
+  const a = Math.sin(half) * radius, b = Math.cos(half) * radius;
+  return (
+    <g transform={'translate(' + x + ',' + y + ')'} opacity={opacity} aria-hidden="true" pointerEvents="none">
+      <defs>
+        <radialGradient id={id} gradientUnits="userSpaceOnUse" cx={0} cy={0} r={radius}>
+          <stop offset="0" stopColor={color} stopOpacity="0" />
+          <stop offset="0.16" stopColor={color} stopOpacity="0.65" />
+          <stop offset="0.42" stopColor={color} />
+          <stop offset="1" stopColor={color} stopOpacity="0" />
+        </radialGradient>
+      </defs>
+      <g className="mp-sunburst-motion" data-sunburst-motion={motion} style={{ '--sunburst-duration': Math.max(0.1, duration) + 's' }}>
+        {Array.from({ length: count }, (_, i) => <path key={i} transform={'rotate(' + (i * 360 / count) + ')'} d={'M0,0 L' + (-a) + ',' + (-b) + ' Q0,' + (-radius) + ' ' + a + ',' + (-b) + ' Z'} fill={'url(#' + id + ')'} />)}
+      </g>
+    </g>
+  );
+}

package/components/effects/Sunburst.prompt.md

@@ -0,0 +1,12 @@
+Sunburst: rays of light behind a focal point, inside an SVG.
+
+```jsx
+<svg viewBox="0 0 400 300">
+  <Sunburst x={200} y={150} radius={260} rays={14} opacity={0.34} duration={90} />
+  {/* the thing it sits behind */}
+</svg>
+```
+
+- It is a `<g>`, not an element, so it only works inside an `<svg>`. Draw it first so the content sits on top.
+- Keep `opacity` low (0.1 to 0.35). It is a glow, not a pattern.
+- `motion="once"` plays a single fade for a reveal; `still` doesn't move. Reduced motion stops all of it.

package/components/feedback/Badge.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+/**
+ * Notification dot / count bubble with a white ring. Pin it to a button or tab corner.
+ * @startingPoint section="Feedback" subtitle="Notification dot + count" viewport="700x120"
+ */
+export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  /** "!" (default) or a number/short string. */
+  count?: React.ReactNode;
+  tone?: 'danger' | 'gold' | 'blue' | 'teal' | 'green';
+  size?: 'sm' | 'md';
+  /** Gentle bob to draw the eye. */
+  pulse?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function Badge(props: BadgeProps): React.JSX.Element;

package/components/feedback/Badge.jsx

@@ -0,0 +1,16 @@
+'use client';
+import React from 'react';
+
+const TONES = { danger: ['var(--coral-300)', 'var(--coral-500)', 'var(--coral-700)'], gold: ['var(--gold-300)', 'var(--gold-500)', 'var(--gold-700)'],
+  blue: ['var(--blue-300)', 'var(--blue-500)', 'var(--blue-700)'], teal: ['var(--teal-300)', 'var(--teal-500)', 'var(--teal-700)'], green: ['var(--green-300)', 'var(--green-500)', 'var(--green-700)'] };
+
+export function Badge({ count = '!', tone = 'danger', size = 'md', pulse = false, style, ...rest }) {
+  const [top, mid, shade] = TONES[tone] || TONES.danger;
+  const d = size === 'sm' ? 18 : 24; const fs = size === 'sm' ? 11 : 13;
+  return (
+    <span style={{ display: 'inline-grid', placeItems: 'center', minWidth: d, height: d, padding: '0 ' + (d * 0.25) + 'px', boxSizing: 'border-box', borderRadius: 'var(--radius-pill)',
+      background: 'linear-gradient(180deg, ' + top + ', ' + mid + ' 55%)', border: '2px solid #fff', boxShadow: '0 2px 0 ' + shade + ', 0 3px 6px oklch(0 0 0 / 0.25)',
+      color: tone === 'gold' ? 'var(--gold-900)' : '#fff', fontFamily: 'var(--font-display)', fontSize: fs, lineHeight: 1, letterSpacing: '0.02em',
+      animation: pulse ? 'mp-float 1.6s ease-in-out infinite' : 'none', ...style }} {...rest}>{count}</span>
+  );
+}

package/components/feedback/Badge.prompt.md

@@ -0,0 +1,10 @@
+Notification badge: red "!" or count pinned to the top-right corner of a button, tab or card (position it absolutely from the parent).
+
+```jsx
+<div style={{ position: 'relative' }}>
+  <IconButton variant="primary" shape="square"><GameIcon kind="quest" outline={false} shadow={false} /></IconButton>
+  <Badge count={3} style={{ position: 'absolute', top: -6, right: -6 }} />
+</div>
+<Badge />                       // "!"
+<Badge count="NEW" tone="gold" size="sm" />
+```

package/components/feedback/ErrorText.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+
+/**
+ * A short coral error line for under a form or field. Renders nothing without a message, and is announced to screen readers when one appears.
+ * @startingPoint section="Feedback" subtitle="Coral error line, announced" viewport="700x120"
+ */
+export interface ErrorTextProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  children?: React.ReactNode;
+}
+
+export function ErrorText(props: ErrorTextProps): React.JSX.Element | null;

package/components/feedback/ErrorText.jsx

@@ -0,0 +1,8 @@
+'use client';
+import React from 'react';
+
+/* A short error under a form or a field. Renders nothing when there is no message, and is announced when one appears. */
+export function ErrorText({ children, className, ...rest }) {
+  if (!children) return null;
+  return <p className={['mp-error-text', className].filter(Boolean).join(' ')} role="alert" {...rest}>{children}</p>;
+}

package/components/feedback/ErrorText.prompt.md

@@ -0,0 +1,9 @@
+Error text: one line that says what went wrong and what to do.
+
+```jsx
+<ErrorText>{error}</ErrorText>
+<ErrorText>That link has expired. Ask for a new one.</ErrorText>
+```
+
+- Always render it and pass the message, which may be empty: with nothing to say it disappears.
+- Say how to fix it, not just what broke.

package/components/feedback/LoadingScreen.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+
+/**
+ * The boot screen: sky, drifting clouds, the title, a striped gold bar that grows and shrinks, and a hill with the road setting off. Fills the window.
+ * @startingPoint section="Feedback" subtitle="Full-window boot screen" viewport="700x420"
+ */
+export interface LoadingScreenProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** The name shown big above the bar. Left out when empty. */
+  title?: string;
+  /** The words under the bar. Default "Loading…". */
+  label?: string;
+}
+
+export function LoadingScreen(props: LoadingScreenProps): React.JSX.Element;

package/components/feedback/LoadingScreen.jsx

@@ -0,0 +1,24 @@
+'use client';
+import React from 'react';
+import { OutlineText } from '../text/OutlineText';
+
+/* The boot screen: sky with a few drifting clouds, the title, a striped gold bar in its track, and a hill with the road setting off.
+   Fills the window. Give it a title; the label under the bar is the accessible name. */
+export function LoadingScreen({ title, label = 'Loading…', className, ...rest }) {
+  return (
+    <div className={['mp-loading', className].filter(Boolean).join(' ')} role="status" aria-label="Loading" {...rest}>
+      <span className="mp-loading-cloud mp-loading-cloud-a" aria-hidden="true" />
+      <span className="mp-loading-cloud mp-loading-cloud-b" aria-hidden="true" />
+      <span className="mp-loading-cloud mp-loading-cloud-c" aria-hidden="true" />
+      <div className="mp-loading-stack">
+        {title && <OutlineText as="p" size={40} color="gold" stroke="ink" style={{ margin: 0, textAlign: 'center', textWrap: 'balance' }}>{title}</OutlineText>}
+        <span className="mp-loading-track" aria-hidden="true"><span className="mp-loading-fill" /></span>
+        <OutlineText as="span" size={18} color="white" stroke="ink" style={{ letterSpacing: '0.04em' }}>{label}</OutlineText>
+      </div>
+      <div className="mp-loading-ground" aria-hidden="true">
+        <span className="mp-loading-hill" />
+        <span className="mp-loading-road" />
+      </div>
+    </div>
+  );
+}

package/components/feedback/LoadingScreen.prompt.md

@@ -0,0 +1,9 @@
+Loading screen: what shows while the app gets ready.
+
+```jsx
+if (!session) return <LoadingScreen title="The Birthday Adventure" />;
+```
+
+- It fills the window (`min-height: 100dvh`), so render it instead of the screen, not inside it. In a smaller box, give it a height.
+- Pass the app's name as `title`. Without one, the bar and label still show.
+- The bar and clouds keep moving until the screen is replaced, and stop for reduced motion.

package/components/feedback/Notice.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * A card with a round sticker and a message: a quiet note, a warning, or a celebration. It slides up when it appears, and warnings are announced.
+ * @startingPoint section="Feedback" subtitle="Sticker and message card: info, warn, gold" viewport="700x360"
+ */
+export interface NoticeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** info is the quiet cream card, warn is coral and announced, gold is for celebration. */
+  tone?: 'info' | 'warn' | 'gold';
+  /** A Phosphor icon name without the prefix. Default "info". */
+  icon?: string;
+  children?: React.ReactNode;
+}
+
+export function Notice(props: NoticeProps): React.JSX.Element;

package/components/feedback/Notice.jsx

@@ -0,0 +1,16 @@
+'use client';
+import React from 'react';
+import { Sticker } from './Sticker';
+
+const STICKER_TONE = { info: 'blue', warn: 'coral', gold: 'gold' };
+
+/* A card with a sticker and a message. Warnings are announced to screen readers when they appear. */
+export function Notice({ tone = 'info', icon = 'info', children, className, ...rest }) {
+  const cls = ['mp-notice', tone === 'warn' ? 'mp-notice-warn' : tone === 'gold' ? 'mp-notice-gold' : '', className].filter(Boolean).join(' ');
+  return (
+    <div className={cls} role={tone === 'warn' ? 'alert' : undefined} {...rest}>
+      <Sticker icon={icon} tone={STICKER_TONE[tone] || 'blue'} />
+      <div>{children}</div>
+    </div>
+  );
+}

package/components/feedback/Notice.prompt.md

@@ -0,0 +1,10 @@
+Notice: a short message with a sticker beside it.
+
+```jsx
+<Notice icon="envelope-simple">Your note is on its way.</Notice>
+<Notice tone="warn" icon="warning">That photo is too large. Try one under 10 MB.</Notice>
+<Notice tone="gold" icon="gift">Everything is in. Nicely done.</Notice>
+```
+
+- Use `warn` only for things that went wrong. It is announced to screen readers, so don't show one unless something needs attention.
+- Keep it to a sentence or two. For a single line under a field, use `ErrorText`.

package/components/feedback/SaveAlert.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * The full message behind a failed save: a conflict says what happened and offers Reload, an error says it will retry. Renders nothing otherwise.
+ * @startingPoint section="Feedback" subtitle="Conflict and error messages for autosave" viewport="700x140"
+ */
+export interface SaveAlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  status?: 'saved' | 'saving' | 'pending' | 'error' | 'conflict';
+  /** The reason. For a conflict it is the whole message; for an error it follows "Not saved yet:". */
+  error?: string | null;
+  /** Shows a Reload button on a conflict. */
+  onReload?: () => void;
+}
+
+export function SaveAlert(props: SaveAlertProps): React.JSX.Element | null;

package/components/feedback/SaveAlert.jsx

@@ -0,0 +1,24 @@
+'use client';
+import React from 'react';
+
+/* The full message behind a failed save. A conflict is announced as an alert, with a Reload link when onReload is given;
+   an error is a status line. Renders nothing when the save is fine. */
+export function SaveAlert({ status, error, onReload, className, ...rest }) {
+  const cls = ['mp-save-alert', className].filter(Boolean).join(' ');
+  if (status === 'conflict') {
+    return (
+      <div className={cls} role="alert" {...rest}>
+        <i className="ph-fill ph-warning" aria-hidden="true" /> {error}
+        {onReload && <button type="button" className="mp-link-button" onClick={onReload}>Reload</button>}
+      </div>
+    );
+  }
+  if (status === 'error') {
+    return (
+      <div className={cls} role="status" {...rest}>
+        <i className="ph-fill ph-cloud-slash" aria-hidden="true" /> Not saved yet: {error ?? 'retrying when you edit'}
+      </div>
+    );
+  }
+  return null;
+}

package/components/feedback/SaveAlert.prompt.md

@@ -0,0 +1,9 @@
+Save alert: the plain-words version of a save that didn't go through. Pair it with `SavePill`.
+
+```jsx
+<SavePill status={status} />
+<SaveAlert status={status} error={saveError} onReload={() => location.reload()} />
+```
+
+- A `conflict` is announced right away and should say that someone else changed this; give it `onReload` so there is a way out.
+- An `error` is a quiet status line. With no reason given it says it will retry when the person edits again.

package/components/feedback/SavePill.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+/**
+ * The autosave state for a HUD, as a round cloud: it bobs while saving, pops once saved, and shows its word for a moment when pressed. Errors show "Not saved" and stay on screen.
+ * @startingPoint section="Feedback" subtitle="Autosave cloud: saving, saved, not saved" viewport="700x140"
+ */
+export interface SavePillProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  status?: 'saved' | 'saving' | 'pending' | 'error' | 'conflict';
+  /** How long the word stays after a press, in ms. Default 2500. */
+  wordMs?: number;
+}
+
+export function SavePill(props: SavePillProps): React.JSX.Element;

package/components/feedback/SavePill.jsx

@@ -0,0 +1,29 @@
+'use client';
+import React, { useEffect, useState } from 'react';
+
+/* The autosave state for a HUD, as a cloud that sits on its own so nothing crowds the screen. Pressing it shows the word for a moment.
+   Errors stay spelled out. status is 'saved', 'saving', 'pending', 'error' or 'conflict'. */
+export function SavePill({ status = 'saved', wordMs = 2500, className, ...rest }) {
+  const [word, setWord] = useState(false);
+  useEffect(() => {
+    if (!word) return undefined;
+    const t = setTimeout(() => setWord(false), wordMs);
+    return () => clearTimeout(t);
+  }, [word, wordMs]);
+  if (status === 'conflict' || status === 'error') {
+    return (
+      <span className={['mp-save-pill mp-save-pill-warn', className].filter(Boolean).join(' ')} aria-hidden="true" {...rest}>
+        <i className="ph-fill ph-cloud-slash" /> Not saved
+      </span>
+    );
+  }
+  const saved = status === 'saved';
+  const label = saved ? 'Saved' : 'Saving';
+  return (
+    <button type="button" className={['mp-save-pill', saved ? 'mp-save-pill-pop' : 'mp-save-pill-busy', word ? '' : 'mp-save-pill-icon', className].filter(Boolean).join(' ')}
+      onClick={() => setWord(true)} aria-label={label} {...rest}>
+      <i key={status} className={'ph-fill ' + (saved ? 'ph-cloud-check' : 'ph-cloud-arrow-up')} aria-hidden="true" />
+      <span className={word ? 'mp-save-word' : 'mp-sr'} role="status" aria-live="polite">{label}</span>
+    </button>
+  );
+}

package/components/feedback/SavePill.prompt.md

@@ -0,0 +1,8 @@
+Save pill: whether the person's changes are safe, in the corner of a HUD.
+
+```jsx
+<SavePill status={saveStatus} />
+```
+
+- Pass the editor's own status: `saved`, `saving` or `pending`, `error` or `conflict`. It only draws the state, so it doesn't save anything itself.
+- On `error` and `conflict` it can't be pressed and says "Not saved". Put a `SaveAlert` where there's room, so the reason and a way out are on screen too.

package/components/feedback/SoundToggle.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+/**
+ * Sound on/off pill with glyph AND text, so the state never relies on colour. Lives on the opening screen and in the HUD.
+ * @startingPoint section="Feedback" subtitle="Sound on / off control" viewport="700x100"
+ */
+export interface SoundToggleProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'style'> {
+  on?: boolean;
+  onChange?: (on: boolean) => void;
+  /** dark over the world (default) · light inside panels. */
+  tone?: 'dark' | 'light';
+  size?: 'sm' | 'md';
+  style?: React.CSSProperties;
+}
+
+export function SoundToggle(props: SoundToggleProps): React.JSX.Element;

package/components/feedback/SoundToggle.jsx

@@ -0,0 +1,15 @@
+'use client';
+import React from 'react';
+
+export function SoundToggle({ on = true, onChange, tone = 'dark', size = 'md', style, ...rest }) {
+  const h = size === 'sm' ? 36 : 44, dark = tone === 'dark';
+  return (
+    <button type="button" role="switch" aria-checked={on} onClick={() => onChange && onChange(!on)}
+      style={{ display: 'inline-flex', alignItems: 'center', gap: 8, height: h, padding: '0 16px 0 12px', borderRadius: 999, cursor: 'pointer', border: '2px solid ' + (dark ? 'oklch(0.2 0.05 55 / 0.9)' : 'var(--cream-300)'),
+        background: dark ? 'var(--surface-hud)' : 'var(--cream-50)', color: dark ? '#fff' : 'var(--ink-900)', boxShadow: dark ? 'inset 0 2px 4px oklch(0 0 0 / 0.35), 0 2px 0 oklch(1 0 0 / 0.15)' : '0 3px 0 var(--cream-300)',
+        fontFamily: 'var(--font-display)', fontSize: size === 'sm' ? 13 : 15, letterSpacing: '0.04em', textTransform: 'uppercase', textShadow: dark ? '0 2px 0 oklch(0 0 0 / 0.35)' : 'none', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      <i key={on ? 'on' : 'off'} className={'ph-fill ph-' + (on ? 'speaker-high' : 'speaker-slash')} aria-hidden="true" style={{ fontSize: h * 0.5, lineHeight: 1, color: on ? (dark ? 'var(--teal-300)' : 'var(--teal-700)') : (dark ? 'var(--coral-300)' : 'var(--coral-700)'), animation: 'mp-pop var(--dur-slow) var(--ease-bounce) both' }} />
+      <span>{on ? 'Sound on' : 'Sound off'}</span>
+    </button>
+  );
+}

package/components/feedback/SoundToggle.prompt.md

@@ -0,0 +1,6 @@
+Sound toggle: sound starts only after a deliberate tap (the opening's Ready button); this control lets the recipient change their mind anywhere.
+
+```jsx
+<SoundToggle on={sound} onChange={setSound} />
+<SoundToggle on={sound} onChange={setSound} tone="light" size="sm" />
+```

package/components/feedback/Sticker.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * A round bevelled badge holding one white glyph, tinted from a colour family. Decorative, so pair it with words.
+ * @startingPoint section="Feedback" subtitle="Round bevelled glyph badge in 7 tones" viewport="700x120"
+ */
+export interface StickerProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style' | 'children'> {
+  /** A Phosphor icon name without the prefix, such as "heart" or "warning". */
+  icon: string;
+  tone?: 'blue' | 'teal' | 'gold' | 'coral' | 'berry' | 'green' | 'stone';
+  weight?: 'fill' | 'bold';
+  style?: React.CSSProperties;
+}
+
+export function Sticker(props: StickerProps): React.JSX.Element;

package/components/feedback/Sticker.jsx

@@ -0,0 +1,12 @@
+'use client';
+import React from 'react';
+
+/* A round bevelled badge holding one white glyph. Decorative: it is hidden from screen readers, so say the same thing in words beside it. */
+export function Sticker({ icon, tone = 'blue', weight = 'fill', style, ...rest }) {
+  const vars = { '--tone-hi': 'var(--' + tone + '-300)', '--tone-face': 'var(--' + tone + '-500)', '--tone-side': 'var(--' + tone + '-700)', ...style };
+  return (
+    <span className="mp-sticker" style={vars} aria-hidden="true" {...rest}>
+      <i className={'ph-' + weight + ' ph-' + icon} />
+    </span>
+  );
+}

package/components/feedback/Sticker.prompt.md

@@ -0,0 +1,9 @@
+Sticker: a round glyph badge that gives a line of copy a small visual anchor.
+
+```jsx
+<Sticker icon="heart" tone="berry" />
+<Sticker icon="warning" tone="coral" weight="bold" />
+```
+
+- It is hidden from screen readers, so never let it carry meaning alone.
+- `tone` picks a colour family (its 300, 500 and 700 shades make the highlight, face and side). Prefer `Notice` when the sticker sits beside a message.

package/components/feedback/Tag.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * Small uppercase label chip: MOST POPULAR, 3X VALUE, ONE-TIME OFFER, NEW. Sits on a card edge or next to a title.
+ * @startingPoint section="Feedback" subtitle="Uppercase label chip in 8 tones" viewport="700x120"
+ */
+export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'style'> {
+  tone?: 'danger' | 'gold' | 'teal' | 'blue' | 'berry' | 'green' | 'stone' | 'wood';
+  size?: 'sm' | 'md';
+  icon?: React.ReactNode;
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+}
+
+export function Tag(props: TagProps): React.JSX.Element;

package/components/feedback/Tag.jsx

@@ -0,0 +1,15 @@
+'use client';
+import React from 'react';
+
+const TONES = { danger: ['var(--coral-500)', 'var(--coral-700)', '#fff'], gold: ['var(--gold-500)', 'var(--gold-700)', 'var(--gold-900)'], teal: ['var(--teal-500)', 'var(--teal-700)', '#fff'],
+  blue: ['var(--blue-500)', 'var(--blue-700)', '#fff'], berry: ['var(--berry-500)', 'var(--berry-700)', '#fff'], green: ['var(--green-500)', 'var(--green-700)', '#fff'], stone: ['var(--stone-500)', 'var(--stone-700)', '#fff'], wood: ['var(--wood-500)', 'var(--wood-700)', '#fff'] };
+
+export function Tag({ tone = 'danger', size = 'md', icon, children, style, ...rest }) {
+  const [bg, shade, text] = TONES[tone] || TONES.danger;
+  const h = size === 'sm' ? 18 : 24; const fs = size === 'sm' ? 10 : 12;
+  return (
+    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 4, height: h, padding: '0 ' + (h * 0.4) + 'px', borderRadius: 'var(--radius-xs)', boxSizing: 'border-box',
+      background: bg, boxShadow: '0 2px 0 ' + shade + ', inset 0 1px 0 oklch(1 0 0 / 0.45)', color: text, fontFamily: 'var(--font-display)', fontSize: fs, lineHeight: 1, letterSpacing: '0.06em', textTransform: 'uppercase',
+      whiteSpace: 'nowrap', ...style }} {...rest}>{icon}{children}</span>
+  );
+}

package/components/feedback/Tag.prompt.md

@@ -0,0 +1,10 @@
+Label chip: merchandising and status labels; 1–3 uppercase words.
+
+```jsx
+<Tag>Most popular</Tag>
+<Tag tone="teal">3x the value</Tag>
+<Tag tone="gold" size="sm">New</Tag>
+<Tag tone="stone" icon={<i className="ph-fill ph-lock" />}>Locked</Tag>
+```
+
+- danger (coral) for scarcity, teal/green for value, gold for new/featured, berry for premium, stone for locked.

package/components/feedback/Toast.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+/**
+ * Reward / status toast: dark pill that pops in with a bounce. Position it from the parent (usually top-center or above the bottom bar).
+ * @startingPoint section="Feedback" subtitle="Bouncing reward toast" viewport="700x140"
+ */
+export interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Leading glyph, e.g. <GameIcon kind="coin" size={32} />. */
+  icon?: React.ReactNode;
+  /** Headline in display type, e.g. "+50". */
+  message: React.ReactNode;
+  /** Small UI-type line under the headline, e.g. "Coins collected". */
+  detail?: React.ReactNode;
+  /** Headline color. */
+  tone?: 'gold' | 'blue' | 'teal' | 'coral' | 'berry' | 'white';
+  /** Renders nothing when false. */
+  visible?: boolean;
+  style?: React.CSSProperties;
+}
+
+export function Toast(props: ToastProps): JSX.Element | null;

package/components/feedback/Toast.jsx

@@ -0,0 +1,19 @@
+'use client';
+import React from 'react';
+
+const TONES = { gold: 'var(--gold-300)', blue: 'var(--blue-300)', teal: 'var(--teal-300)', coral: 'var(--coral-300)', berry: 'var(--berry-300)', white: '#fff' };
+
+export function Toast({ icon, message, detail, tone = 'gold', visible = true, style, ...rest }) {
+  if (!visible) return null;
+  return (
+    <div role="status" style={{ display: 'inline-flex', alignItems: 'center', gap: 10, height: 52, padding: '0 20px 0 12px', borderRadius: 'var(--radius-pill)', boxSizing: 'border-box',
+      background: 'var(--surface-hud)', border: '2px solid oklch(0.20 0.05 55 / 0.9)', boxShadow: 'var(--shadow-drop), inset 0 2px 0 oklch(1 0 0 / 0.12)',
+      animation: 'mp-pop var(--dur-slow) var(--ease-bounce) both', ...style }} {...rest}>
+      {icon}
+      <div style={{ display: 'flex', flexDirection: 'column', lineHeight: 1.05 }}>
+        <span style={{ fontFamily: 'var(--font-display)', fontSize: 20, color: TONES[tone] || tone, textShadow: '0 2px 0 oklch(0 0 0 / 0.35)', letterSpacing: '0.02em' }}>{message}</span>
+        {detail && <span style={{ fontFamily: 'var(--font-ui)', fontWeight: 700, fontSize: 12, color: 'oklch(1 0 0 / 0.8)' }}>{detail}</span>}
+      </div>
+    </div>
+  );
+}

package/components/feedback/Toast.prompt.md

@@ -0,0 +1,7 @@
+Reward toast: confirms a pickup or a state change without a dialog; auto-dismiss after ~1.6s from the parent.
+
+```jsx
+<Toast icon={<GameIcon kind="coin" size={32} />} message="+50" detail="Coins collected" />
+<Toast icon={<GameIcon kind="heart" size={32} />} message="Life restored" tone="coral" />
+<Toast message="Saved" tone="teal" />
+```

package/components/forms/Slider.d.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * Volume-style slider: inset dark track, colored fill, chunky bevelled grip knob. Wraps a native range input for accessibility.
+ * @startingPoint section="Forms" subtitle="Volume slider with grip knob" viewport="700x140"
+ */
+export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'onChange'> {
+  value?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  onChange?: (value: number) => void;
+  tone?: 'blue' | 'teal' | 'gold' | 'green' | 'berry';
+  /** Leading glyph (e.g. <GameIcon kind="music" />). */
+  icon?: React.ReactNode;
+  /** Total width incl. icon. Default 220. */
+  width?: number | string;
+  disabled?: boolean;
+  /** Accessible name. */
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function Slider(props: SliderProps): React.JSX.Element;

package/components/forms/Slider.jsx

@@ -0,0 +1,28 @@
+'use client';
+import React from 'react';
+
+export function Slider({ value = 50, min = 0, max = 100, step = 1, onChange, tone = 'blue', icon, width = 220, disabled = false, label, style, ...rest }) {
+  const pct = ((value - min) / ((max - min) || 1)) * 100;
+  const c = ['var(--' + tone + '-300)', 'var(--' + tone + '-500)', 'var(--' + tone + '-700)'];
+  const h = 18, kw = 28, kh = 36;
+  return (
+    <div style={{ display: 'inline-flex', alignItems: 'center', gap: 12, width, opacity: disabled ? 0.6 : 1, ...style }} {...rest}>
+      {icon}
+      <div style={{ position: 'relative', flex: 1, height: kh, display: 'flex', alignItems: 'center' }}>
+        <div style={{ position: 'absolute', left: 0, right: 0, height: h, borderRadius: 'var(--radius-pill)', background: 'linear-gradient(180deg, var(--stone-700), var(--stone-500))',
+          boxShadow: 'inset 0 2px 4px oklch(0 0 0 / 0.4), 0 2px 0 oklch(1 0 0 / 0.5)', overflow: 'hidden' }}>
+          <div style={{ position: 'absolute', left: 0, top: 0, bottom: 0, width: 'calc(' + pct + '% + ' + (kw / 2) + 'px)', borderRadius: 'inherit',
+            background: 'linear-gradient(180deg, ' + c[0] + ', ' + c[1] + ' 60%, ' + c[2] + ')', boxShadow: 'inset 0 2px 0 oklch(1 0 0 / 0.5)' }} />
+        </div>
+        <div aria-hidden="true" style={{ position: 'absolute', left: 'calc(' + pct + '% - ' + (pct / 100) * kw + 'px)', width: kw, height: kh, borderRadius: 'var(--radius-sm)',
+          background: 'linear-gradient(180deg, ' + c[0] + ', ' + c[1] + ' 50%)', boxShadow: '0 3px 0 ' + c[2] + ', 0 5px 8px oklch(0 0 0 / 0.3), inset 0 2px 0 oklch(1 0 0 / 0.5)',
+          display: 'grid', placeItems: 'center', gridAutoFlow: 'column', gap: 3, pointerEvents: 'none' }}>
+          <span style={{ width: 3, height: 14, borderRadius: 2, background: c[2], boxShadow: '0 1px 0 oklch(1 0 0 / 0.4)' }} />
+          <span style={{ width: 3, height: 14, borderRadius: 2, background: c[2], boxShadow: '0 1px 0 oklch(1 0 0 / 0.4)' }} />
+        </div>
+        <input type="range" aria-label={label} min={min} max={max} step={step} value={value} disabled={disabled} onChange={e => onChange && onChange(Number(e.target.value))}
+          style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', margin: 0, opacity: 0, cursor: disabled ? 'default' : 'pointer' }} />
+      </div>
+    </div>
+  );
+}

package/components/forms/Slider.prompt.md

@@ -0,0 +1,6 @@
+Volume slider: music/SFX levels in Settings; also brightness or speed. Always pair with a leading GameIcon.
+
+```jsx
+<Slider value={music} onChange={setMusic} icon={<GameIcon kind="music" />} label="Music" />
+<Slider value={70} tone="teal" icon={<GameIcon kind="sound" tone="teal" />} width={260} />
+```

package/components/forms/Switch.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+/**
+ * Chunky on/off toggle with an inset track and a bevelled knob that bounces across.
+ * @startingPoint section="Forms" subtitle="Inset toggle, teal/blue/gold" viewport="700x120"
+ */
+export interface SwitchProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'style' | 'onChange'> {
+  checked?: boolean;
+  onChange?: (next: boolean) => void;
+  disabled?: boolean;
+  /** On-state color. Default teal. */
+  tone?: 'teal' | 'blue' | 'gold' | 'green' | 'berry';
+  size?: 'sm' | 'md';
+  /** Accessible name (visible label is rendered by the parent row). */
+  label?: string;
+  style?: React.CSSProperties;
+}
+
+export function Switch(props: SwitchProps): React.JSX.Element;

package/components/forms/Switch.jsx

@@ -0,0 +1,20 @@
+'use client';
+import React from 'react';
+
+export function Switch({ checked = false, onChange, disabled = false, tone = 'teal', size = 'md', label, style, ...rest }) {
+  const w = size === 'sm' ? 44 : 56; const h = size === 'sm' ? 26 : 32; const k = h - 8;
+  const on = ['var(--' + tone + '-300)', 'var(--' + tone + '-500)', 'var(--' + tone + '-700)'];
+  return (
+    <button type="button" role="switch" aria-checked={checked} aria-label={label} disabled={disabled} onClick={() => !disabled && onChange && onChange(!checked)}
+      style={{ appearance: 'none', border: 0, padding: 0, margin: 0, cursor: disabled ? 'default' : 'pointer', position: 'relative', width: w, height: h, flex: 'none', borderRadius: 'var(--radius-pill)',
+        background: checked ? 'linear-gradient(180deg, ' + on[2] + ', ' + on[1] + ')' : 'linear-gradient(180deg, var(--stone-700), var(--stone-500))',
+        boxShadow: 'inset 0 2px 4px oklch(0 0 0 / 0.35), 0 2px 0 oklch(1 0 0 / 0.5)', opacity: disabled ? 0.6 : 1,
+        transition: 'background var(--dur-base)', WebkitTapHighlightColor: 'transparent', ...style }} {...rest}>
+      <span aria-hidden="true" style={{ position: 'absolute', top: 2, left: checked ? w - k - 4 : 2, width: k, height: k, borderRadius: '50%',
+        background: 'linear-gradient(180deg, #fff, var(--cream-100))', boxShadow: '0 2px 0 var(--cream-300), 0 3px 5px oklch(0 0 0 / 0.25)',
+        transition: 'left var(--dur-base) var(--ease-bounce)' }}>
+        <span style={{ position: 'absolute', inset: '30%', borderRadius: '50%', background: checked ? on[1] : 'var(--stone-300)', transition: 'background var(--dur-base)' }} />
+      </span>
+    </button>
+  );
+}