Space Works UX: make the UX spec our own, inspired by Yuyu

README.md

@@ -20,9 +20,9 @@ masters, colours, type, voice, every design token and the UI specs, published fr
 | `icons/` | `favicon.svg`, PNG app icons (16, 32, 180, 192, 512) and the 1200×630 social card |
 | `fonts/` | Gilroy Regular, Medium, Semibold and Bold (WOFF), plus Unbounded (WOFF2). Legacy faces retained for existing consumers. See `fonts/README.md`. |
 | `tokens/` | `tokens.css` (`@font-face` + light/dark colour variables as RGB triplets) and `tokens.json` (the same colours as hex, plus the seven brand colours) |
-| `docs/` | `ui-brand-spec.md` (token derivations, contrast ratios, states, status pills, type scale, logo use), `ux-yuyu-spec.md` (UX patterns from Yuyu, reusable layouts, navigation, screen specs), `ux-screens-longtail.md` (remaining screens) |
+| `docs/` | `ui-brand-spec.md` (token derivations, contrast ratios, states, status pills, type scale, logo use), `ux-spec.md` (**Space Works UX**: our interaction patterns, reusable layouts, navigation and screen specs), `ux-screens-longtail.md` (remaining screens) |
 | `site/` | The Starlight website published to GitHub Pages; `scripts/sync-kit.mjs` copies the kit in at build time |
-| `references/yuyu/` | Reference boards from [Yuyu](https://github.com/twilighty-abhi/yuyu) that the UX patterns and layouts are modelled on |
+| `references/yuyu/` | The reference boards from [Yuyu](https://github.com/twilighty-abhi/yuyu) that inspired Space Works UX |
 
 ## Brand at a glance
 
@@ -51,8 +51,9 @@ Add the class `dark` to `<html>` for dark mode. The font URLs in `tokens.css` ar
 
 ## Credits
 
-The UX patterns, layouts and interaction details are modelled on [Yuyu](https://github.com/twilighty-abhi/yuyu)
-(reference boards in `references/yuyu/`). The visual identity — colour, type, logo, icons and voice — comes only from the Space Works
+**Space Works UX** (the patterns, layouts and interaction details in `docs/ux-spec.md`) is our own
+interaction system. It was inspired by [Yuyu](https://github.com/twilighty-abhi/yuyu), whose screens we
+studied as reference boards (kept in `references/yuyu/`). The visual identity — colour, type, logo, icons and voice — comes only from the Space Works
 brand guidelines in `brand/`.
 
 ## Export provenance

site/astro.config.mjs

@@ -19,7 +19,7 @@ export default defineConfig({
     starlight({
       title: 'Space Works Design',
       description:
-        'The Space Works design system: logo, colour, type, voice, design tokens and UI specs.',
+        'The Space Works design system: logo, colour, type, voice, design tokens, UI specs and Space Works UX.',
       logo: {
         light: './src/assets/kit/lockup-horizontal.svg',
         dark: './src/assets/kit/lockup-horizontal-reversed.svg',
@@ -61,6 +61,7 @@ export default defineConfig({
           ],
         },
         { label: 'Tokens', items: ['tokens/using-the-kit', 'tokens/reference'] },
+        { label: 'UX', items: ['ux/introduction'] },
         { label: 'Specs', items: [{ autogenerate: { directory: 'specs' } }] },
         { label: 'About', items: ['about/credits'] },
       ],

site/scripts/sync-kit.mjs

@@ -35,7 +35,7 @@ cpSync(join(root, 'tokens', 'tokens.json'), join(assets, 'tokens.json'));
 // Spec pages: the first "# Heading" becomes the page title; the rest is published unchanged.
 const specPages = [
   { file: 'ui-brand-spec.md', slug: 'ui-brand-spec', order: 1, label: 'UI brand spec' },
-  { file: 'ux-yuyu-spec.md', slug: 'ux-patterns', order: 2, label: 'UX patterns' },
+  { file: 'ux-spec.md', slug: 'ux-patterns', order: 2, label: 'Space Works UX spec' },
   { file: 'ux-screens-longtail.md', slug: 'ux-long-tail-screens', order: 3, label: 'Long-tail screens' },
 ];
 for (const { file, slug, order, label } of specPages) {

site/src/content/docs/about/credits.md

@@ -9,10 +9,11 @@ The colour, type, logo, icons and voice come only from the Space Works brand gui
 the connected Figma file on 15 October 2026. `brand/figma-styles.json` records the source node IDs, the seven
 paint styles and the ten text styles.
 
-## UX patterns
+## Space Works UX
 
-The UX patterns, layouts and interaction details in the specs are modelled on
-[Yuyu](https://github.com/twilighty-abhi/yuyu). The reference boards are kept in
+[Space Works UX](/ux/introduction/) is our own interaction system: the patterns, layouts and
+interaction details in the specs. It was inspired by [Yuyu](https://github.com/twilighty-abhi/yuyu), whose
+screens we studied as reference boards. The reference boards are kept in
 [`references/yuyu/`](https://github.com/SpaceWorks-HQ/SpaceWorks-Design/tree/main/references/yuyu) and are not
 republished on this site.
 

site/src/content/docs/brand/introduction.mdx

@@ -36,4 +36,5 @@ The symbol is a familiar box, built for a space full of possibilities.
 
 The visual identity comes only from the
 [Space Works brand guidelines](/brand/guidelines/), exported from the Figma file on 15 October 2026. This site
-publishes that kit; when the two disagree, the guidelines win.
+publishes that kit; when the two disagree, the guidelines win. How screens behave comes from
+[Space Works UX](/ux/introduction/), our interaction system.

site/src/content/docs/index.mdx

@@ -35,6 +35,7 @@ structure gives every part a place, and the colours do the rest: teal grounds it
   <LinkCard title="Voice" description="Sound like a helpful maker: clear, warm and specific." href="/brand/voice/" />
   <LinkCard title="Design tokens" description="Every light and dark colour token, ready to import as CSS or JSON." href="/tokens/reference/" />
   <LinkCard title="UI specs" description="How the brand becomes the app: states, pills, type scale and screen patterns." href="/specs/ui-brand-spec/" />
+  <LinkCard title="Space Works UX" description="Our interaction system: 30 patterns, 10 layouts and the quality bar every screen meets." href="/ux/introduction/" />
 </CardGrid>
 
 ## One source of truth

site/src/content/docs/ux/introduction.mdx

@@ -0,0 +1,60 @@
+---
+title: Space Works UX
+description: Our interaction system. The patterns, layouts and quality bar every Space Works screen follows.
+---
+
+import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+**Space Works UX** sets how every Space Works screen works: where things go, how you move between them, and
+what happens when you act. The brand decides how a screen looks. Space Works UX decides how it behaves.
+
+## The rules to remember
+
+<CardGrid>
+  <Card title="One clear next step">
+    One filled primary action per page header, sticky card or callout. Everything else is an outline pill,
+    a text link or a row menu.
+  </Card>
+  <Card title="Calm workspace, warm public face">
+    Staff and manager screens stay quiet: cream canvas, white panels, hairlines, no shadows. Public pages
+    get one bold moment.
+  </Card>
+  <Card title="Do it now, offer Undo">
+    Reversible actions happen straight away and offer Undo in place. Irreversible ones live in a danger
+    zone, behind a button that ends in "…" and a confirmation.
+  </Card>
+  <Card title="Counts where you look">
+    Numbers live on stat cards, tab labels and row slots, so the queue that needs you is never hidden.
+  </Card>
+  <Card title="Empty states name the next step">
+    "No parts added yet. Add your first item." An empty list always says what to do, and says something
+    different when a filter hides everything.
+  </Card>
+  <Card title="Everyone can use it">
+    44 px targets, a visible focus ring, one `h1` per page, a skip link, and tabs that are real URLs.
+  </Card>
+</CardGrid>
+
+## What it covers
+
+- **30 patterns (P1–P30):** the app shell and sidebar, page and detail headers, stat cards, callouts, list
+  rows, tabs, pills, buttons, the activity rail, settings rows, the danger zone, empty states, forms, auth,
+  public pages, kiosk screens, and Undo and confirmation behaviour.
+- **10 layouts (L1–L10):** a closed set. Every screen is the app shell plus exactly one of `AppShell`,
+  `DashboardLayout`, `ListLayout`, `DetailLayout`, `SettingsLayout`, `FormPageLayout`, `FlowLayout`,
+  `AuthLayout` / `CenteredCardLayout`, `PublicLayout` / `PublicDetailLayout` and `KioskLayout`.
+- **Screen specs:** the core screens, then the long-tail screens, each mapped to a layout and its patterns.
+- **A quality bar** that every screen has to pass before it ships.
+
+<CardGrid>
+  <LinkCard title="Space Works UX spec" description="Patterns, layouts, navigation, core screens and the quality bar." href="/specs/ux-patterns/" />
+  <LinkCard title="Long-tail screens" description="The remaining screens, each composed from the same patterns and layouts." href="/specs/ux-long-tail-screens/" />
+  <LinkCard title="UI brand spec" description="How the brand becomes interface: tokens, states, pills and the type scale." href="/specs/ui-brand-spec/" />
+</CardGrid>
+
+## Where it comes from
+
+Space Works UX is our own. It was inspired by [Yuyu](https://github.com/twilighty-abhi/yuyu), whose screens we
+studied as reference boards (R1–R28 in the spec) and then adapted for Space Works: bigger tables, guided
+flows, payments, kiosks and many roles. The visual identity comes only from the
+[Space Works brand guidelines](/brand/guidelines/). See [Credits and licences](/about/credits/).