Skip to content

Add Decorator Kit Developer Guide (user-guide/) - #4

Merged
chorta merged 1 commit into
mainfrom
claude/html-design-guide-41475e
Sep 22, 2026
Merged

chorta merged 1 commit into
mainfrom
claude/html-design-guide-41475e

Conversation

@chorta

@chorta chorta commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

What this adds

A visual guide for developers who build on Decorator 5 with an AI agent, in user-guide/. Every example is live Decorator markup with a prompt you can copy. It's modeled on the v5 kitchen sink, with a prompt added to each example.

index.html: Developer Guide

  • A start-here prompt template, plus diagrams of the four layout templates showing which regions are editable and which are chrome
  • Brand basics: the Decorator colors and typography rules
  • On-brand Bootstrap 3.3.7 components: buttons, .msg alerts, breadcrumbs, forms, input groups, table.styled-dark, drawers, grid and Glyphicons
  • Modules with their documented image sizes, widgets, app recipes, guardrails, and a review prompt

app-patterns.html: App Patterns (under Components in the nav)

  • A page index at the top that links to every pattern, with "Back to page index" links after each section
  • App patterns: tabs, side menu, segmented control, toolbar/item bar, action menu, item and media lists, pagination, modal, responsive helpers. Each is tagged Decorator-styled, Neutral, Brand layer, or Bootstrap docs.
  • Dashboard building blocks: key numbers with trends, data bars, status lists, deadline timelines, checklists, a filter bar
  • 7 app shells (complete screens) and 8 starter dashboards for campus areas: advising, enrollment, research admin, housing and dining, IT status, facilities and sustainability, library, HR onboarding
  • A four-prompt workflow for building a dashboard with an agent: scaffold → static layout → wire data → review and verify

Supporting files

  • css/app-patterns.css: a brand layer that moves stock-blue (#337ab7) Bootstrap components onto the Decorator palette and gives controls 44px touch targets. Every rule is scoped to main#main-content plus an app-* class. Active states key on aria-current, aria-expanded, or :checked, never on .active, .nav, .dropdown-menu, or other chrome classes.
  • css/guide.css: styles for the guide itself, also canvas-scoped
  • js/guide.js: copy-to-clipboard with a screen-reader announcement
  • js/status-board.js: a working, progressively enhanced example with filter, search, and a live count

How it was built

  • Source: both pages start from dist/templates/two-column.html in ucsd-decorator-v5@5.0.4, a template chosen explicitly during the session.
  • Chrome: the header and footer match the template byte for byte. Only the nav-link <ul> in the drawer and in the navbar were changed. Both search blocks are shipped verbatim.
  • Assets: all CSS and JS load from cdn.ucsd.edu. The CDN serves Bootstrap 3.3.7, and the guide refers to that version.
  • Markup: Decorator markup comes from the npm package. Tabs, list groups, media objects, the modal and the radio button group aren't in the package; their markup comes from Bootstrap v3.3.7's docs source (twbs/bootstrap@v3.3.7/docs/_includes/), and each card says so.
  • Class check: every Decorator class shown was checked against the live CDN base.min.css. No -success, -info, -warning, or -danger classes, no <style> blocks, and no inline style attributes.
  • Images: cropped copies of package images at each module's documented size.
  • Not shipped: user-guide/ isn't in package.json files, so it won't go out with the npm package.

Verification

  • node ../checks/chrome-contract.mjs --check, run from user-guide/: no structural or styling findings. The only findings are 6 × chrome/golden/*, "no golden recorded yet". Nobody has run --accept; recording the baseline is a reviewer's call.
  • npm test passes.
  • Headless Chrome tests:
    • The status board filter and search update the count (12 → 3 → 1 → 0), and the empty state appears when nothing matches.
    • Tabs switch correctly.
    • The dropdown opens in Decorator navy.
    • The modal opens and moves focus inside.
    • Every in-page anchor, aria-* reference, and data-copy-target resolves.

For reviewers

  • http:// URLs in the shipped chrome: the template ships two, the white logo img and the desktop search form action. They were copied verbatim because they're in the chrome. Upgrading them to HTTPS needs a human-reviewed chrome change.
  • Site title: the title band still reads "Decorator V5". Changing it to the guide's name is a chrome edit that was deliberately left to a human.
  • Not tested yet:
    • A real phone width (headless Chrome won't render below 485px)
    • A screen reader
    • A real clipboard copy (headless blocks clipboard access, so only the fallback path was exercised)
  • Page length: app-patterns.html is long (about 2,200 lines). The dashboards could move to their own page later without any prompt changes.

🤖 Generated with Claude Code

A visual guide for developers building on Decorator 5 with an AI agent.
Each example is live Decorator markup paired with a copyable prompt.

- index.html: layout templates, brand basics, on-brand Bootstrap 3.3.7
  components, modules with image sizes, widgets, app recipes, guardrails.
- app-patterns.html: in-app navigation, action bars, lists, dialogs,
  helpers, dashboard building blocks, 7 app shells, and 8 starter
  dashboards for campus areas, plus a four-prompt build workflow.
- css/app-patterns.css: brand layer that re-colors stock-blue Bootstrap
  components to the Decorator palette. It is canvas-scoped, and active
  states are keyed on ARIA attributes, never on chrome classes.
- js/status-board.js: a working, progressively enhanced status board.

Both pages start from dist/templates/two-column.html (ucsd-decorator-v5
5.0.4). The chrome is copied verbatim, only the nav-link lists were
changed, and all assets load from cdn.ucsd.edu.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chorta
chorta merged commit 7a20d18 into main Sep 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant