@vibeuncle/gpgb-ui 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+Versions follow semver while 0.x: **minor** = new components or token changes that may shift appearance, **patch** = fixes. Apps pin with `^0.x.0`.
+
+## 0.2.0 — first public release
+- Tokens: paper/ink/accent palette with dark mode, `accent-text`, `border-strong`, `focus`, `on-accent`/`on-danger`; radii, shadows, motion tokens.
+- `ds-*` CSS components and a React package: buttons, forms, cards, badges, tabs, modal, confirm dialog, sheet, menu, popover, tooltip, toast, stamp, skeleton.
+- Navigation: `SiteHeader` (graphic logo + divider), `NavLinks`, `NavDrawer`, `Breadcrumbs`, `StepIndicator`, `UserMenu`, `WorkspaceSwitcher`, `LangToggle`, `SiteFooter`; layouts `PageShell`, `CenteredPage`, `SidebarLayout`, `PageTitle`.
+- `LinkProvider` so apps can supply `next/link`; `containerClassName` and `homeLabel` on `SiteHeader`.
+- zh/en `labels`, focus-trap/dismiss hooks, browser test suite, static style guide, `DESIGN.md` + `DESIGN_SYSTEM.md`.
+- `accent-text` retuned to `#a84a0a` / `#ffb783` so it passes AA on `accent-soft`.

package/DESIGN.md

@@ -0,0 +1,254 @@
+---
+name: 大道大商 Design System
+description: Warm paper, warm ink, one orange. A calm community-bulletin look for 大道大商 apps.
+colors:
+  paper: "#faf6ee"
+  paper-deep: "#f1eadb"
+  surface: "#ffffff"
+  ink: "#221f1a"
+  ink-soft: "#6b6458"
+  ink-faint: "#766e59"
+  border-soft: "#e8e0d1"
+  border-strong: "#8f8676"
+  accent: "#ff7f20"
+  accent-hover: "#d96c1b"
+  accent-soft: "#ffebdb"
+  accent-text: "#a84a0a"
+  focus: "#d96c1b"
+  on-accent: "#ffffff"
+  danger: "#c62828"
+  on-danger: "#ffffff"
+  warn: "#8a5a20"
+  success: "#2e7d4f"
+  scrim: "#1c1a16"
+  paper-dark: "#1c1a16"
+  paper-deep-dark: "#2a2620"
+  surface-dark: "#262320"
+  ink-dark: "#f1ece1"
+  ink-soft-dark: "#b5ac9c"
+  ink-faint-dark: "#948c73"
+  border-soft-dark: "#3a352c"
+  border-strong-dark: "#7d7463"
+  accent-dark: "#ff994d"
+  accent-hover-dark: "#ffac6e"
+  accent-soft-dark: "#664921"
+  accent-text-dark: "#ffb783"
+  focus-dark: "#ff994d"
+  on-accent-dark: "#221f1a"
+  on-danger-dark: "#221f1a"
+  danger-dark: "#f87171"
+  warn-dark: "#e0b06a"
+  success-dark: "#6fcf97"
+typography:
+  display:
+    fontFamily: "Noto Serif SC, Songti SC, serif"
+    fontSize: "2.25rem to 3rem"
+    fontWeight: 500
+    lineHeight: 1.2
+    letterSpacing: "-0.025em"
+  title:
+    fontFamily: "Noto Serif SC, Songti SC, serif"
+    fontSize: "1.25rem"
+    fontWeight: 500
+    lineHeight: 1.2
+  body:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 400
+    lineHeight: 1.6
+  reading:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "16px"
+    lineHeight: 1.85
+    letterSpacing: "0.01em"
+  reading-wide:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "17px"
+    lineHeight: 1.85
+    letterSpacing: "0.01em"
+  button-lg:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "15px"
+    fontWeight: 500
+  hint:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "12px"
+    lineHeight: 1.6
+  caption:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "12px"
+    fontWeight: 400
+    letterSpacing: "0.08em"
+  badge-sm:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "11px"
+    fontWeight: 500
+    letterSpacing: "0.05em"
+  code:
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace"
+    fontSize: "12px"
+  label:
+    fontFamily: "Noto Sans SC, PingFang SC, system-ui, sans-serif"
+    fontSize: "13px"
+    fontWeight: 500
+rounded:
+  xs: "4px"
+  sm: "6px"
+  md: "8px"
+  lg: "12px"
+  xl: "16px"
+  pill: "9999px"
+spacing:
+  xs: "4px"
+  sm: "8px"
+  md: "16px"
+  lg: "24px"
+  xl: "40px"
+components:
+  button-primary:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.on-accent}"
+    rounded: "{rounded.pill}"
+    padding: "10px 20px"
+  button-primary-hover:
+    backgroundColor: "{colors.accent-hover}"
+  button-outline:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.pill}"
+    padding: "10px 20px"
+  button-ghost:
+    backgroundColor: "{colors.paper}"
+    textColor: "{colors.ink-soft}"
+    rounded: "{rounded.pill}"
+  button-danger:
+    backgroundColor: "{colors.danger}"
+    textColor: "{colors.on-danger}"
+    rounded: "{rounded.pill}"
+  input:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.md}"
+    padding: "10px 14px"
+  card:
+    backgroundColor: "{colors.surface}"
+    rounded: "{rounded.lg}"
+  modal:
+    backgroundColor: "{colors.surface}"
+    rounded: "{rounded.xl}"
+    padding: "24px"
+  badge-accent:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.on-accent}"
+    rounded: "{rounded.pill}"
+    padding: "4px 12px"
+  tab-selected:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.on-accent}"
+    rounded: "{rounded.sm}"
+---
+
+# Design System: 大道大商
+
+Source: `styles/tokens.css` and `styles/components.css`. Rendered reference: `styleguide/index.html`. Usage guide: `DESIGN_SYSTEM.md`.
+Derived from the shipped build, not from intentions. The creative direction below was inferred from the existing apps (greatpath-draw reference) and was not interviewed; confirm or rename it.
+
+## Overview
+
+**Creative North Star: "The Community Bulletin."** A well-kept notice board in a warm room: cream paper, dark ink, a single orange seal of approval. Calm, legible, a little editorial. It is a working tool for volunteers and small teams, so it favours scanability and trust over spectacle.
+
+- Pages are cream (`paper`); content sits on white `surface`; text is warm near-black `ink`. Dark mode is the same room at night: charcoal paper, cream ink, a lighter orange.
+- Orange is the only brand colour and is rare by design: primary action, selection, focus, hover. One primary button per view.
+- Serif (Noto Serif SC) carries voice, titles and quotes. Sans (Noto Sans SC) does the work, including all long reading.
+- Shapes are soft (pills and rounded cards) with hairline borders and faint shadows. Motion is short and quiet.
+- Light/dark follows the OS (`prefers-color-scheme`); `data-theme` forces one for previews.
+
+## Colors
+
+Strategy: restrained. Warm neutrals do 90% of the work; orange appears as fills, rings and small accents.
+
+- **Surfaces:** `paper` page, `paper-deep` recessed panels and table hover, `surface` cards/inputs/modals.
+- **Text:** `ink` body and headings; `ink-soft` secondary; `ink-faint` hints and placeholders (never on `paper-deep`, 4.2:1 there).
+- **Lines:** `border-soft` for decorative dividers and card edges; `border-strong` for anything that must be perceivable as a control (input edges, switch track), 3:1+.
+- **Accent family:** `accent` for fills; `accent-hover` for pressed/hover fills and the light-mode focus ring; `accent-soft` for tints and selected-row washes; `accent-text` when orange must read as text or an icon (raw `accent` is only 2.3:1 on paper).
+- **On-fill text:** `on-accent` is white in light (the reference look, 2.5:1) and ink in dark (7.8:1; white would be 2.1:1). `on-danger` is white in light mode, ink in dark.
+- **Feedback:** `danger`, `warn`, `success` are text/border colours, with dark-mode counterparts. `scrim` is the overlay base and stays dark in both themes.
+
+Rule: no raw hex in app code; no Tailwind red/gray/orange.
+
+## Typography
+
+- **Display** (`font-display`): Noto Serif SC 500, tracking -0.025em, line-height 1.2, balanced wrapping. Page title 36 to 48px; section titles 20 to 24px.
+- **Body:** Noto Sans SC 14px / 1.6. Secondary copy in `ink-soft`; hints 12px `ds-hint`.
+- **Reading** (`font-answer`): 16px (17px from 640px), line-height 1.85, strict CJK line-breaking. Sans on purpose: serif hairlines break up on phones.
+- **Editorial** (`font-editorial`): serif at 1.85 for quotes.
+- **Caption** (`ds-caption`): 12px, uppercase, tracking .08em. Short labels only; never for sentences.
+- Bilingual labels: Chinese first, English after or beneath. Numerals in tables are tabular.
+
+## Layout
+
+- 4px base. Page gutter 24px; `ds-container` max 72rem. Card padding 16 to 24px; field gap 16px; button icon gap 8px.
+- Mobile-first; `sm` (640px) is the phone/tablet switch. On touch (`pointer: coarse`) inputs are 16px (no iOS zoom) and buttons are 44px tall; switches get a 44px hit area; tabs 40px.
+- Sections separate with generous vertical space (40px) and a hairline; groups inside stay tight.
+
+## Elevation & Depth
+
+Mostly flat: hairline borders do the separating. Shadows are soft with offset and blur: `sm` at rest (cards, primary button), `md` on hover or raise, `lg` for modals and toasts. Dark mode deepens the shadow alpha. Overlays use `scrim` at 75%, with no blur.
+
+## Shapes
+
+Pill for anything you press or read as a label (buttons, badges, toasts). 16px modals, 12px cards, 8px inputs and tab groups, 6px tab items and skeletons. Images inside cards are clipped to the card radius.
+
+## Components
+
+- **Button:** pill, 14px/500. Variants primary (accent fill, on-accent text), outline, ghost, danger. Sizes sm, md, lg, icon. States: hover (darker fill or accent-soft wash, ghost text goes `accent-text`), press (scale .97), focus (2px `focus` ring, 2px offset), disabled (.45 opacity), loading (`aria-busy`, label hidden, spinner). Icon-only needs `aria-label`.
+- **Input / textarea / select:** 8px, `border-strong` edge, hover to `ink-soft`, focus ring in `focus` with matching border, error via `aria-invalid` (danger border and ring) plus a `ds-error` message with `role=alert`. Checkbox and radio are native, `accent-color` orange.
+- **Switch:** 40x24 pill, `role=switch`; off track `border-strong`, on track `accent`, white thumb.
+- **Card:** surface, 1px `border-soft`, 12px, shadow-sm. Interactive card: border to accent and shadow-md on hover.
+- **Badge:** pill; accent, ink, tint, outline, danger tones; small variant 11px uppercase.
+- **Tabs / segmented:** `border-soft` group, 6px items, selected = accent fill with on-accent text. Toggle groups use `aria-pressed`, real tabs `aria-selected`.
+- **Modal:** surface, 16px, shadow-lg, backdrop-in then modal-in (200ms). Esc and backdrop close; scroll locked; labelled. Footer: outline cancel, then the primary or danger action.
+- **Toast:** top-centre pill, ink fill with paper text (danger fill for errors), 3s.
+- **Alert:** inline, 8px, accent-soft default, danger and warn outlined. **Empty state:** serif title, hint, one action. **Skeleton** mirrors final layout; **spinner** only for short waits.
+- **Table:** hairline rows, 12px/14px cells, tabular numerals, hover `paper-deep`.
+- **Header:** hairline bottom, graphic logo (h-6), a 1px vertical hairline divider (20px, `border-strong` at 55%) so the lettering mark and the app name don't read as one phrase, then the serif app title, optional nav, right-aligned actions; skip link to main. The logo flips to light in dark mode, including the manual toggle.
+- **Navigation:** pill nav links (current = `accent-soft` wash, `aria-current="page"`); below 768px they move to a left drawer behind a menu button. Breadcrumbs for depth 3+. Step indicator: done = ink check, current = accent dot on a tint, upcoming = outline. Footer: small logo, copyright, links.
+- **Menu / popover / tooltip:** surface panel, 1px `border-soft`, 12px, shadow-md, 6px padding; items 8px radius with an `accent-soft` hover/focus wash and an inset `focus` ring; separators `border-soft`; destructive items in `danger`. Tooltip: ink bubble with paper text, 12px, 350ms delay, hidden on touch.
+- **Sheet:** bottom sheet (16px top radius, grab handle) or left drawer (320px max); slides 300ms; closed = inert; focus trapped while open.
+- **Account:** 32px avatar (accent-soft, initial) opening a menu; workspace switcher is an outline pill with a chevron and a 仅查看 badge for viewers.
+- **Layouts:** PageShell (header, 72rem container, footer), CenteredPage (one 400px, 16px-radius card on paper), SidebarLayout (240px sticky aside from 1024px; a bottom sheet on phones).
+- **Browser surfaces:** caret and checkboxes orange; selection is `accent-soft`; scrollbar thumbs `border-soft`; links underline at 4px offset on hover.
+
+## Voice
+
+Warm, plain, respectful; Chinese first, English beside or beneath. Buttons are verb + object (保存海报, never 确定). Errors give the cause, then the fix. Empty states say what belongs there plus one action. Chinese uses full-width punctuation and a space before numbers and Latin words. English is sentence case.
+
+## Motion
+
+Calm, physical, short: things settle into place like paper on a board. Tokens: 150ms (hover, press), 200ms (modal, slide, card lift), 350ms (list entry), 560ms (stamp); entrances use `cubic-bezier(.16,1,.3,1)`, the switch thumb settles with `cubic-bezier(.34,1.25,.64,1)`.
+
+The one authored moment is the **seal stamp** (`ds-stamp`): an orange seal with an inner ring that lands from 1.8x scale and -16deg, settles at -6deg, and sends out one fading ring. Used once per view, on a meaningful success. Supporting motion is quiet feedback: staggered list entry (45ms steps, first load only), scroll reveal (CSS scroll timeline, no JS), card lift of 2px, link underline drawing in from the left, a switch thumb with a small spring, and a skeleton sweep. Modals use backdrop-in then modal-in; toasts drop 12px.
+
+Only transform, opacity and shadow animate, never layout. `prefers-reduced-motion` removes all of it.
+
+## Do's and Don'ts
+
+Do
+- Use tokens and `ds-*` classes; one primary button per view.
+- Use `accent-text` when orange is text; `border-strong` for control edges; `focus` for rings.
+- Keep serif for titles and quotes, sans for everything else.
+- Give every state (hover, focus, disabled, loading, error, empty) a treatment.
+
+Don't
+- Use a menu for a hint, a tooltip for required information, or a modal for a task that needs neither interruption nor protected focus.
+- Use orange-fill labels below 14px or below medium weight in light mode, or put white text on orange in dark mode. Orange as text must use `accent-text` (4.5:1 on paper).
+- Use `ink-faint` on `paper-deep`, or `border-soft` as the only edge of a form control.
+- Add colour beyond the tokens, a second brand colour, gradient text, or side-stripe borders on cards and alerts.
+- Use caption (uppercase) styling for sentences, or Unicode glyphs in place of icons (Lucide, 16 to 20px, stroke 2).
+- Animate layout, or replay entrances on content people are reading.
+- Use the stamp more than once per view, or for anything minor.
+
+## Known exceptions
+
+- White on orange fills in light mode is 2.5:1 (3.4:1 on hover), below AA. Accepted to match greatpath-draw. Mitigation: labels stay 14px+ medium, never the only signal, and focus uses the separate `focus` token.
+- Disabled controls (.45 opacity) are exempt from contrast by WCAG.

package/DESIGN_SYSTEM.md

@@ -0,0 +1,165 @@
+# 大道大商 Design System (`@vibeuncle/gpgb-ui`)
+
+Source of truth for the shared look of draw.gpgb.app, albums, jiqun-studio, jielong and future 大道大商 apps.
+Reference app: **greatpath-draw**. Where apps disagreed, greatpath-draw won; gaps were filled from jiqun-studio
+(feedback colours, shadows, radii, `ds-*` classes), gpgb-albums (easing) and jielong (`paper-deep`).
+
+## Principles
+1. **Warm paper + ink.** Pages are cream (`paper`), content sits on white `surface`, text is warm near-black `ink`.
+2. **One orange.** `accent` (#ff7f20, the VI primary) is the only brand colour: primary action, focus, selection, links on hover. One primary button per view.
+3. **Soft shapes.** Pills for actions and labels, rounded cards, hairline borders. Shadows are faint.
+4. **Serif for voice, sans for work.** Noto Serif SC for titles and quotes; Noto Sans SC for everything else, including long reading text.
+5. **Quiet motion.** Short ease-out entrances that answer an action; nothing loops except spinners/skeletons. Reduced-motion flattens all of it.
+6. **Dark mode is automatic** (`prefers-color-scheme`); never branch on theme in components, use tokens.
+
+## Colour tokens
+| Token | Light | Dark | Use |
+|---|---|---|---|
+| `paper` | #faf6ee | #1c1a16 | Page background |
+| `paper-deep` | #f1eadb | #2a2620 | Recessed panels, table hover |
+| `surface` | #ffffff | #262320 | Cards, inputs, modals |
+| `ink` | #221f1a | #f1ece1 | Body/headings |
+| `ink-soft` | #6b6458 | #b5ac9c | Secondary text |
+| `ink-faint` | #766e59 | #948c73 | Hints, placeholders (AA on paper) |
+| `border-soft` | #e8e0d1 | #3a352c | Decorative dividers, card edges |
+| `border-strong` | #8f8676 | #7d7463 | Form-control edges, switch track (3:1+) |
+| `accent` / `-hover` / `-soft` | #ff7f20 / #d96c1b / #ffebdb | #ff994d / #ffac6e / #664921 | Brand fill, hover, tinted bg |
+| `accent-text` | #a84a0a | #ffb783 | Orange used as text/icon (4.8:1+ on paper, surface, paper-deep and accent-soft; raw accent is 2.3:1 on paper) |
+| `focus` | #d96c1b | #ff994d | Focus ring (3:1+) |
+| `danger` | #c62828 | #f87171 | Errors, destructive |
+| `warn` | #8a5a20 | #e0b06a | Warnings |
+| `success` | #2e7d4f | #6fcf97 | Confirmations |
+| `on-accent` | #ffffff | #221f1a | Text on accent fills. White in light (reference look), ink in dark |
+| `on-danger` | #ffffff | #221f1a | Text on danger fills |
+| `scrim` | #1c1a16 | same | Overlays (always dark) |
+
+Use as Tailwind utilities: `bg-paper text-ink-soft border-border-soft`. No raw hex in app code. Don't use Tailwind's red/gray/orange.
+
+## Typography
+- Display: `font-display` (Noto Serif SC 500, tracking -0.025em, lh 1.2). Page title `text-4xl sm:text-5xl`; section `text-xl`.
+- Body: Noto Sans SC 14px (`text-sm`), lh 1.6. Secondary copy `text-ink-soft`; hints `ds-hint` (12px).
+- Reading text: `font-answer` (16px phone / 17px sm+, lh 1.85, strict CJK line-breaking). Editorial quotes: `font-editorial`.
+- Eyebrow/caption: `ds-caption` (12px, uppercase, tracking .08em).
+- Bilingual labels: Chinese first, English in `ds-hint` beneath or after a `·`. Don't mix scripts mid-label in different fonts. `lang="zh-CN"` on `<html>`.
+- Load fonts via `fonts.css` (fontsource) or `next/font` exposing the same family names. Brand-VI commercial fonts are not bundled.
+
+## Shape, elevation, spacing
+- Radii: `pill` buttons/badges/toasts; `xl` 16 modals & hero cards; `lg` 12 cards; `md` 8 inputs/tabs; `sm` 6 tab items/skeletons. Images in cards: `lg` clipped.
+- Shadows: `sm` cards at rest, `md` hover/raised, `lg` modals/toasts. Borders stay 1px `border-soft`.
+- Spacing: 4px base; page gutter 24px (`ds-container`, max 72rem); card padding 16–24px; gap between form fields 16px; button gap 8px.
+- Breakpoints: Tailwind defaults; design mobile-first, `sm` 640 is the phone/tablet switch.
+
+## Components (all `ds-*` classes; React wrappers in `src/`)
+| Component | Class / React | Notes |
+|---|---|---|
+| Button | `ds-btn ds-btn-{primary,outline,ghost,danger}` `-sm -lg -icon` / `<Button>` | Pill. Press = scale .97. Disabled .45 opacity. Loading = `aria-busy="true"`. Icon-only needs `aria-label`. Primary left→right order: cancel(outline), confirm(primary). |
+| Input/Textarea/Select | `ds-input` `-sm` / `<Input>` … | 8px radius; focus = accent border + ring; error = `aria-invalid` (danger border) + `ds-error`. Wrap with `<Field>` for label/hint/error. |
+| Switch | `ds-switch` / `<Switch>` | `role=switch`; 44px hit area. |
+| Checkbox/radio | `ds-check` | Native control, orange `accent-color`. |
+| Card | `ds-card` `-interactive` / `<Card>` | Clickable cards get `-interactive` (accent border + shadow-md on hover). |
+| Badge/chip | `ds-badge-{accent,ink,tint,outline,danger}` `-sm` / `<Badge>` | Status = tint/outline; count/new = accent. |
+| Tabs | `ds-tabs` `ds-tab` / `<Tabs>` | Segmented; selected = solid accent with on-accent text. Toggle groups: `aria-pressed`. |
+| Modal | `ds-backdrop ds-modal` / `<Modal>` | Esc/backdrop close, scroll lock, `aria-labelledby`. Enter: backdrop-in + modal-in. |
+| Toast | `ds-toast` `-error` / `<Toast>` | Top-centre pill, 3s. |
+| Alert | `ds-alert` `-danger -warn` / `<Alert>` | Inline, persistent messages. |
+| Empty state | `ds-empty` / `<EmptyState>` | Serif title, hint, one action. |
+| Skeleton/Spinner | `ds-skeleton`, `ds-spinner` | Skeleton mirrors final layout; spinner only for <3s waits. |
+| Table | `ds-table` | Hairline rows, hover `paper-deep`. |
+| Header | `ds-header` / `<SiteHeader>` | Graphic logo `assets/logo/daoshang-horizontal-mark-dark.png` (h-6, `brand-logo` flips it light in dark mode; also `…-bare-dark.png` without the brush mark) + a 1px vertical hairline (`ds-brand-divider`, 20px tall, `border-strong` at 55%) + serif app title + right-aligned actions. The divider separates the brand mark from the app name because the mark is lettering; it shows only when there is an app title. Copy the file into the app's `public/logo/`. |
+| Link | `ds-link` | Soft ink, accent + underline on hover. |
+
+## Motion
+Principle: calm, physical, short. Things settle into place like paper on a bulletin board; the single flourish is the **seal stamp**.
+Tokens: `--duration-fast` 150ms (hover/press), `--duration-base` 200ms (modal, slide, lift), `--duration-slow` 350ms (list entry), `--duration-stamp` 560ms; `--ease-out` cubic-bezier(.16,1,.3,1) for entrances, `--ease-spring` for a gentle settle (switch thumb), `--ease-standard` for state changes, `--stagger-step` 45ms.
+
+| Pattern | Class | Use |
+|---|---|---|
+| Entrances | `animate-backdrop-in`, `animate-modal-in`, `animate-entry-in`, `animate-slide-next/prev`, `toast-in` (built into `ds-toast`) | Overlays, panels, toasts, stepped flows |
+| Stagger | `ds-stagger` on a list/grid parent | First load of lists, galleries, dashboards. 45ms steps, capped at 12 |
+| Scroll reveal | `ds-reveal` | Long pages. CSS scroll timeline, no JS; unsupported browsers just show it |
+| Seal stamp | `ds-stamp` / `<Stamp>` | Once per view on a meaningful success (published, saved, signed up) |
+| Card lift | `ds-card-interactive` | Clickable cards: rise 2px + deeper shadow, settle on press |
+| Link underline | `ds-link` | Underline draws in from the left on hover |
+| Switch | `ds-switch` | Thumb settles with a small overshoot |
+| Skeleton | `ds-skeleton` | Soft sweep while loading (not a blink) |
+| Slideshow | `animate-fade-in` + `animate-drift` | Photo cross-fade and slow Ken Burns (from gpgb-albums) |
+
+Rules: one flourish per view; everything else is quiet feedback that answers an action. Move at most 10px (the stamp excepted). Animate transform, opacity and shadow only, never layout. Stagger only on first load, never replay entrances on content people are reading. Nothing loops except spinner and skeleton. `prefers-reduced-motion` removes all animation and transition, scroll reveal included.
+
+## Navigation
+| Piece | React | Notes |
+|---|---|---|
+| Header | `<SiteHeader logoSrc title nav actions menuButton containerClassName homeLabel>` | Graphic logo left; `nav` shows from `md`; `menuButton` shows below `md`. Includes a skip link to `#main` (give your `<main>` that id). `containerClassName` sets the content width (default 72rem `ds-container`; narrow apps pass e.g. `mx-auto max-w-2xl px-5`). Put short always-visible links in `actions` instead of `nav`. |
+| Nav links | `<NavLinks items>` / `ds-nav-link` | Pill links; current = accent-soft wash + `aria-current="page"`. |
+| Phone nav | `<MenuButton>` + `<NavDrawer items open onOpenChange>` | Left drawer (`Sheet side="left"`). Closes on link click, Esc, scrim. |
+| Account | `<UserMenu>` / `<SignInButton>` | Avatar + menu: settings, extras, sign out. Signed out: outline 登录 button. |
+| Workspace | `<WorkspaceSwitcher workspaces activeId onSwitch>` | Menu of radios; viewer role shows a "仅查看" badge. Reserve its width with a skeleton while loading. The app performs the switch. |
+| Language | `<LangToggle value onChange>` | 中 / EN, `aria-pressed`. The app owns persistence. |
+| Breadcrumbs | `<Breadcrumbs items>` | Depth 3+ only. Last item = current page, not a link. |
+| Steps | `<StepIndicator steps current>` | Done = ink check, current = accent, upcoming = outline. Phones show only the current label. |
+| Footer | `<SiteFooter logoSrc links note>` | Small logo, copyright, links. |
+
+## Menus, popovers, tooltips, sheets
+Pick by job: **Menu** = list of actions; **Popover** = a little extra content or mini form; **Tooltip** = a name or shortcut for an icon button (never required info; hidden on touch); **ConfirmDialog** = before anything irreversible; **Sheet** = phone bottom sheet or nav drawer; **Modal** = a task that needs protected focus.
+- Menu: opens below (`align="end"` for right-edge triggers), focuses the first item however it opens, Arrow/Home/End move (disabled items skipped), Esc closes and returns focus to the trigger, Enter/Space selects. Items with `href` render as links; `checked` makes a radio item; `danger` colours destructive items.
+- Modal, ConfirmDialog and Sheet trap focus, close on Esc, lock scroll and restore focus to the opener. Footer order: outline cancel, then the primary or danger action, whose label names the action ("删除海报", not "确定").
+- Positioning is simple (below the trigger, start or end aligned); there is no collision flipping yet. Keep triggers away from the bottom edge, or use a Sheet on phones.
+
+## Page layouts
+`<PageShell header footer>` (header, 72rem container, footer: lists, galleries, dashboards) · `<CenteredPage>` (one 400px card: sign-in, invite, not-found) · `<SidebarLayout aside>` (240px sticky aside from `lg`; on phones move the aside into a bottom Sheet: editors, settings, admin) · `<PageTitle title description actions breadcrumbs>` (serif title, primary action first on phones).
+
+## Content & voice
+Warm, plain, respectful: a helpful neighbour at the community centre. Chinese (简体) first, English beside or beneath. Say what happened and what to do next; never blame the person.
+| Situation | Say | Avoid |
+|---|---|---|
+| Button | 保存海报 · Save poster (verb + object) | 确定 · OK · Submit |
+| Destructive confirm | 删除海报 (names the thing) | 确定 · Yes |
+| Error | 上传失败，图片超过 10 MB。请压缩后重试。 | 出错了！错误代码 500 |
+| Empty state | 还没有海报。从模板开始，或上传背景图。 | 暂无数据 |
+| Success | 已发布。 · Published. | 操作成功！ |
+| Loading (over 1s) | 正在生成海报… | 请稍候 |
+| Permission | 你只有查看权限。联系管理员可申请编辑。 | 无权访问 |
+Rules: cancel is always 取消 / Cancel. Errors give the cause then the fix, no codes up front, no "Oops". Empty states say what belongs there plus one action. The seal stamp is for big successes only. Chinese uses full-width punctuation (，。：); English uses sentence case, never all-caps sentences. Put a space between Chinese and numbers or Latin words (更新于 3 分钟前). Dates: 2026年10月5日 / 5 Oct 2026. Don't translate proper names. Icon-only buttons carry an `aria-label` in the page language.
+Code: `labels.zh` / `labels.en` (and `t(lang, key)`) hold the standard strings (取消, 确认, 保存, 删除, 关闭, 重试, 返回, 下一步, 登录, 退出登录, 设置, 帮助…). Components accept `lang="zh" | "en"` (default zh).
+
+## Accessibility baseline
+- Focus: `:focus-visible` 2px `focus` outline, 2px offset (inputs: 1px offset, border matches). Never `outline: none` without a replacement.
+- Contrast: text meets AA in both themes (see the Contrast table in the style guide). Known gap: white on orange fills is 2.5:1 in light (3.4:1 on hover), below AA. Accepted to keep greatpath-draw's look: keep those labels 14px+ medium weight and never let them carry meaning alone. Dark mode uses ink on orange (7.8:1) because white would be 2.1:1. Orange as text uses `accent-text`. `ink-faint` is for paper/surface only, not `paper-deep`. Form-control edges use `border-strong` (3:1+); focus rings use `focus`.
+- Touch: coarse pointers get 16px inputs (stops iOS zoom) and 44px min button height. No tap highlight/300ms delay.
+- Semantics: dialogs `role=dialog aria-modal` with focus trap and restore; menus `role=menu/menuitem(radio)` with roving arrow keys; tabs `role=tablist/tab/aria-selected`; toggle groups `aria-pressed`; nav `aria-current="page"`, steps `aria-current="step"`; toasts `status`/`alert`; closed sheets are `inert`; icons that carry meaning have labels.
+- Icons: Lucide, 16–20px, stroke 2, inherit `currentColor`.
+
+## Using it in an app
+```bash
+npm install @vibeuncle/gpgb-ui   # pin with ^0.x; Renovate/Dependabot keeps it current
+```
+```css
+/* app/globals.css */
+@import 'tailwindcss';
+@import '@vibeuncle/gpgb-ui/styles.css';
+@import '@vibeuncle/gpgb-ui/fonts.css';  /* optional */
+```
+```tsx
+import { Button, Card, Modal } from '@vibeuncle/gpgb-ui'
+```
+Next.js: wrap the app once in `<LinkProvider value={Link}>` (`import Link from 'next/link'`) so nav, breadcrumbs, footer and menu links do client-side navigation (default is a plain `<a>`, i.e. full page loads). Add `transpilePackages: ['@vibeuncle/gpgb-ui']` to `next.config.ts` (the package ships TS source). `styles.css` already contains `@source '../src'`, so your Tailwind generates the utilities the React components use; no extra setup. Components are client components where they need state (`'use client'` is in the files).
+
+## Migration map (when you adopt it)
+| App's old name | Canonical |
+|---|---|
+| gpgb-albums `brand`, `brand-dark`, `brand-soft` | `accent`, `accent-hover`, `accent-soft` |
+| gpgb-albums `ink-900/800/700`, `hairline`, `paper-100`, `night` | `ink`, `ink` / `ink-soft`, `border-soft`, `paper-deep`, `scrim` |
+| jielong `seal`, `seal-deep`, `seal-wash`, `card`, `hairline` | `accent`, `accent-hover`, `accent-soft`, `surface`, `border-soft` |
+| jiqun-studio `--brand-orange`, `--grey-*`, `--ochre-600` and other legacy aliases | `accent`, `border-soft`/`ink-soft`, `warn` |
+| greatpath-draw inline `rounded-lg bg-accent …` buttons / `bg-red-600` toasts | `<Button>`, `<Toast tone="error">` |
+| greatpath-draw `MobileSheet`, `WorkspaceSwitcher`, `StepIndicator`, `PosterPreviewModal` shell | `<Sheet>`, `<WorkspaceSwitcher>`, `<StepIndicator>`, `<Modal>` |
+| jiqun-studio `BrandHeader`, `UserMenu`, `LangToggle` · jielong `SiteHeader` · albums `site-header`/`account-bar` | `<SiteHeader>`, `<UserMenu>`, `<LangToggle>` (+ `<NavLinks>` / `<NavDrawer>`) |
+| `text-white` on `bg-accent` / `bg-brand` / `bg-seal` | `text-on-accent` (white in light, ink in dark). Orange text on paper: `text-accent-text` |
+| `border-border-soft` on inputs | `border-border-strong` (use `ds-input`) |
+Colour values already match, so renames are mechanical. The one visual change is dark mode, where text on orange becomes ink.
+
+## Theme preview
+`data-theme="light|dark"` on any element forces that theme for it (the style guide uses this on `<html>`); otherwise the OS setting applies. Visual reference: `styleguide/index.html` (rebuild with `npm run styleguide:build`). Machine-readable spec: `DESIGN.md`.
+
+## Governance
+Change tokens here first, then bump the apps; never edit a copy inside an app. Add a component only when 2+ apps need it. Update this file and `styles/` in the same commit.

package/README.md

@@ -0,0 +1,23 @@
+# @vibeuncle/gpgb-ui
+Shared 大道大商 design system. Spec: [DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md).
+- `styles/tokens.css` — Tailwind v4 `@theme` tokens + dark mode
+- `styles/components.css` — `ds-*` component classes, motion, a11y base
+- `src/` — React components: Button, Field/Input/Select/Switch, Card/Badge/Alert/EmptyState, Tabs, Modal, ConfirmDialog, Sheet, Menu, Popover, Tooltip, Toast, Stamp, SiteHeader, NavLinks/NavDrawer, Breadcrumbs, StepIndicator, UserMenu, WorkspaceSwitcher, LangToggle, PageShell/CenteredPage/SidebarLayout/PageTitle, SiteFooter; `copy.ts` (zh/en labels); `hooks.ts` (focus trap, dismiss, scroll lock)
+- `assets/logo/` — the graphic logo
+- `styleguide/` — static visual reference (open `index.html`)
+No apps are migrated yet. `npm run typecheck` needs react/lucide-react/typescript installed.
+
+## Install
+```bash
+npm install @vibeuncle/gpgb-ui        # peers: react, tailwindcss ^4, lucide-react
+```
+Then follow "Using it in an app" in [DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md) (CSS import, `transpilePackages`, `LinkProvider`).
+
+## Releasing
+1. Change tokens/components; update the style guide and docs in the same commit; add a `CHANGELOG.md` entry.
+2. `npm run check` (typecheck + browser tests; also runs in CI).
+3. `npm version minor` (or `patch`), then `git push --follow-tags`.
+4. The tag triggers `.github/workflows/release.yml`, which publishes to npm when the repo secret `NPM_TOKEN` is set. Or publish by hand: `npm publish`.
+5. Apps pick it up via Renovate/Dependabot PRs (or `npm update @vibeuncle/gpgb-ui`).
+
+Licence: proprietary (`UNLICENSED`): published for 大道大商 / VibeUncle apps, no reuse grant.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@vibeuncle/gpgb-ui",
+  "version": "0.2.0",
+  "description": "大道大商 shared design system: tokens, CSS components, React components, style guide",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chambre-HA/gpgb-ui.git"
+  },
+  "homepage": "https://github.com/chambre-HA/gpgb-ui#readme",
+  "bugs": {
+    "url": "https://github.com/chambre-HA/gpgb-ui/issues"
+  },
+  "keywords": [
+    "design-system",
+    "tailwind",
+    "react",
+    "nextjs",
+    "大道大商"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "src",
+    "styles",
+    "assets",
+    "DESIGN.md",
+    "DESIGN_SYSTEM.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tokens.css": "./styles/tokens.css",
+    "./components.css": "./styles/components.css",
+    "./fonts.css": "./styles/fonts.css",
+    "./styles.css": "./styles/index.css",
+    "./logo/*": "./assets/logo/*"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "tailwindcss": "^4",
+    "lucide-react": ">=0.400"
+  },
+  "peerDependenciesMeta": {
+    "lucide-react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5",
+    "@tailwindcss/cli": "^4",
+    "@types/react-dom": "^19",
+    "esbuild": "^0.25",
+    "lucide-react": "^0.562.0",
+    "react": "^19",
+    "react-dom": "^19",
+    "tailwindcss": "^4"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "styleguide:build": "tailwindcss -i styleguide/input.css -o styleguide/styleguide.css --minify",
+    "test": "node test/run.mjs",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check",
+    "release": "npm run check && npm version"
+  }
+}

package/src/cn.ts

@@ -0,0 +1,3 @@
+export function cn(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(' ')
+}

package/src/components/Account.tsx

@@ -0,0 +1,57 @@
+'use client'
+import { ChevronDown, LogIn, LogOut, Settings } from 'lucide-react'
+import { t } from '../copy'
+import { useLink } from '../link'
+import type { Lang } from '../copy'
+import { Menu } from './Popover'
+import type { MenuEntry } from './Popover'
+import { Badge } from './Surface'
+
+export function Avatar({ name, src }: { name: string; src?: string }) {
+  return <span className="ds-avatar" aria-hidden>{src ? <img src={src} alt="" /> : name.trim().slice(0, 1).toUpperCase()}</span>
+}
+
+/** Signed-in user control. Signed out, render a "登录" Button instead. `extra` items go above Sign out. */
+export function UserMenu({ name, email, avatarSrc, onSettings, settingsHref, onSignOut, extra = [], lang }: {
+  name: string; email?: string; avatarSrc?: string; onSettings?: () => void; settingsHref?: string; onSignOut: () => void; extra?: MenuEntry[]; lang?: Lang
+}) {
+  const items: MenuEntry[] = [
+    { type: 'label', label: email ? `${name} · ${email}` : name },
+    ...(onSettings || settingsHref ? [{ label: t(lang, 'settings'), icon: <Settings size={16} aria-hidden />, onSelect: onSettings, href: settingsHref } as MenuEntry] : []),
+    ...extra,
+    { type: 'separator' },
+    { label: t(lang, 'signOut'), icon: <LogOut size={16} aria-hidden />, onSelect: onSignOut },
+  ]
+  return (
+    <Menu align="end" label={t(lang, 'account')} items={items}
+      trigger={<button type="button" className="ds-btn ds-btn-ghost ds-btn-sm" aria-label={`${t(lang, 'account')}: ${name}`}><Avatar name={name} src={avatarSrc} /><ChevronDown size={14} aria-hidden /></button>} />
+  )
+}
+
+export function SignInButton({ onClick, href, lang }: { onClick?: () => void; href?: string; lang?: Lang }) {
+  const Link = useLink()
+  const cls = 'ds-btn ds-btn-outline ds-btn-sm'
+  return href
+    ? <Link className={cls} href={href}><LogIn size={16} aria-hidden />{t(lang, 'signIn')}</Link>
+    : <button type="button" className={cls} onClick={onClick}><LogIn size={16} aria-hidden />{t(lang, 'signIn')}</button>
+}
+
+export interface WorkspaceOption { id: string; name: string; role?: string }
+
+/** Shows the active workspace and switches between the ones you belong to. The app performs the switch (and any reload).
+ *  Reserve its footprint while the list loads (render <Skeleton className="h-[34px] w-36" />) so the header doesn't reflow. */
+export function WorkspaceSwitcher({ workspaces, activeId, onSwitch, footer, lang }: {
+  workspaces: WorkspaceOption[]; activeId: string; onSwitch: (id: string) => void; footer?: MenuEntry[]; lang?: Lang
+}) {
+  const active = workspaces.find(w => w.id === activeId) ?? workspaces[0]
+  const items: MenuEntry[] = [
+    { type: 'label', label: t(lang, 'switchWorkspace') },
+    ...workspaces.map(w => ({ label: w.name, checked: w.id === active?.id, hint: w.role === 'viewer' ? t(lang, 'viewer') : undefined, onSelect: () => w.id !== active?.id && onSwitch(w.id) }) as MenuEntry),
+    ...(footer?.length ? [{ type: 'separator' } as MenuEntry, ...footer] : []),
+  ]
+  return (
+    <Menu label={t(lang, 'workspace')} items={items}
+      trigger={<button type="button" className="ds-btn ds-btn-outline ds-btn-sm" aria-label={`${t(lang, 'workspace')}: ${active?.name}`}>
+        <span className="max-w-[10rem] truncate">{active?.name}</span>{active?.role === 'viewer' && <Badge tone="outline" small>{t(lang, 'viewer')}</Badge>}<ChevronDown size={14} aria-hidden /></button>} />
+  )
+}

package/src/components/Button.tsx

@@ -0,0 +1,26 @@
+import type { ButtonHTMLAttributes } from 'react'
+import { cn } from '../cn'
+
+export type ButtonVariant = 'primary' | 'outline' | 'ghost' | 'danger'
+export type ButtonSize = 'sm' | 'md' | 'lg' | 'icon'
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant
+  size?: ButtonSize
+}
+
+export function buttonClass(variant: ButtonVariant = 'primary', size: ButtonSize = 'md', extra?: string) {
+  return cn(
+    'ds-btn',
+    `ds-btn-${variant}`,
+    size === 'sm' && 'ds-btn-sm',
+    size === 'lg' && 'ds-btn-lg',
+    size === 'icon' && 'ds-btn-icon',
+    extra,
+  )
+}
+
+/** Pill button. Use one `primary` per view; `outline` for secondary, `ghost` for toolbars. Icon-only needs aria-label. */
+export function Button({ variant, size, className, type = 'button', ...rest }: ButtonProps) {
+  return <button type={type} className={buttonClass(variant, size, className)} {...rest} />
+}