# UiPack

> Jun Xiong's own design system for his sites and work presentations: diagrams, slides, web pages, motion and 3D, as React and SVG components with the rules for writing and laying them out. The Markdown in this package is written for agents; the docs site (https://ui.junxiong.dev) renders the same files and serves each one as Markdown at its repo path.

Agents: read docs/agents/README.md first, then the skill for your job in skills/ (README.md indexes them); the design system itself starts at docs/system/README.md. Agent instructions are in AGENTS.md. Generated from playground/docs-manifest.ts by `npm run docs:sync`; do not edit by hand.

Install (ES modules only; not on npm): `npm install https://github.com/ong6/uipack/releases/download/v0.5.0/uipack-0.5.0.tgz`.

## Start here

- [What UiPack is](https://ui.junxiong.dev/docs/README.md): What UiPack is, who it is for (people and agents), how its layers fit, where to start and how to install it, then every page of the docs.
- [Install and use](https://ui.junxiong.dev/README.md): Install the package, draw a first figure, and the entries for charts, articles, 3D, web pages, decks and docs.

## For agents

- [How agents use UiPack](https://ui.junxiong.dev/docs/agents/README.md): The read order for an agent: the job's skill, the site's spec, the core rules, then the parts; what is fixed and what each site sets.
- [Multi-agent build](https://ui.junxiong.dev/docs/agents/multi-agent-build.md): How a lead splits a website across subagents: what the lead owns, what a subagent never decides, the hand-off and the review pass.
- [Subagent brief](https://ui.junxiong.dev/docs/agents/subagent-brief.md): The copy-paste brief for one subagent building one page or section: inputs, limits, outputs and the self-check.
- [Starting a new website](https://ui.junxiong.dev/docs/agents/new-website.md): A new site gets its spec first: write it from the template, check it, register it, then build.

## Rules

- [Overview](https://ui.junxiong.dev/docs/system/README.md): The core rules: the philosophy, the three independent layers (style, writing, layout), what each owns and where one leaks into another.
- [Style contract](https://ui.junxiong.dev/docs/system/style.md): The roles every site spec fills and the ornament slots it paints, with this site's values (Technical) live.
- [Writing](https://ui.junxiong.dev/docs/system/writing/README.md): The writing rules, by kind of text, and every length they state, generated from the code.
- [Writing: General rules](https://ui.junxiong.dev/docs/system/writing/general.md): The rules every kind of text follows, where each word lives, and every slot's text budget.
- [Writing: Talks and slides](https://ui.junxiong.dev/docs/system/writing/talks.md): How to write a deck you present: titles, points, speaker cues, order and the ask.
- [Writing: Read-alone documents](https://ui.junxiong.dev/docs/system/writing/documents.md): How to write what is read without its author: pre-reads, read-alone decks, documentation, articles.
- [Writing: Web and landing copy](https://ui.junxiong.dev/docs/system/writing/web.md): How to write a product or launch page: the goal, the hero, section heads, proof and the FAQ.
- [Writing: Figure labels and captions](https://ui.junxiong.dev/docs/system/writing/figures.md): How to write a figure's words: caption, labels, arrows, statistics, motion beats and 3D stops.
- [Layout](https://ui.junxiong.dev/docs/system/layout/README.md): The layout floors every site keeps, the library of layout archetypes a spec picks from, and the layout of figures, motion and 3D.
- [Layout: Landing](https://ui.junxiong.dev/docs/system/layout/landing.md): The product landing archetype: its grid, section archetypes, order, and product surfaces at a phone's width.
- [Layout: Documentation](https://ui.junxiong.dev/docs/system/layout/documentation.md): The docs shell archetype: a reading page's regions and the order inside it.
- [Layout: Article](https://ui.junxiong.dev/docs/system/layout/article.md): The layered long read archetype: one text column and the parts of each section.
- [Layout: Deck slide](https://ui.junxiong.dev/docs/system/layout/deck-slide.md): The slide canvas archetype: the canvas, the regions every slide shares, the slide archetypes and the transitions.
- [Layout: Dashboard](https://ui.junxiong.dev/docs/system/layout/dashboard.md): The one-question dashboard archetype: its regions, equal boxes, and the narrow form.
- [What a spec may set](https://ui.junxiong.dev/docs/system/spec-settings.md): The boundary between a site spec and the core rules: a site's look, layout, writing style and component looks, and what holds on every site.
- [Do and don't](https://ui.junxiong.dev/docs/system/do-and-dont.md): Paired examples of the rules, drawn live, and the checklist of generic AI-landing tropes to keep out.

## Recipes

- [Recipes overview](https://ui.junxiong.dev/docs/recipes/README.md): One recipe per page type: the section order, the parts to use, and the rules each relies on.
- [Build a landing page](https://ui.junxiong.dev/docs/recipes/landing.md): Build a landing page: the section order the example renders, the parts per section, the steps.
- [Build a docs page](https://ui.junxiong.dev/docs/recipes/documentation.md): Build a reading page: the order inside it, the docs and article parts, the steps.
- [Build a deck](https://ui.junxiong.dev/docs/recipes/deck-slide.md): Build a deck: the storylines, the slide roles, the parts and every check lintDeck runs.
- [Build a dashboard](https://ui.junxiong.dev/docs/recipes/dashboard.md): Build a dashboard: the order, the parts, the steps.

## Components

- [Architecture diagrams](https://ui.junxiong.dev/docs/diagrams.md): The diagram catalogue: each figure pattern once, from the bare canvas to a figure you drill into, with the parts it is built from.
- [Drill-down figures](https://ui.junxiong.dev/docs/drill.md): A stack of figures where a node zooms open into its own figure: the parts, keyboard, reduced motion and export.
- [Figure parts API](https://ui.junxiong.dev/docs/figure-api.md): Every figure part and its props, the connector rule, hover, motion, theming, the seven presets and static SVG export.
- [Charts](https://ui.junxiong.dev/docs/charts.md): SpanChart and LayerStack: layered and comparative charts for articles, static HTML with no JavaScript.
- [Article parts](https://ui.junxiong.dev/docs/article.md): The labelled blocks of a long article section, with their HTML and class contract.
- [Article parts: Verification](https://ui.junxiong.dev/docs/article-verification.md): How the article parts are tested, the measured section rhythm and screenshots.
- [Deck player: Tech talk](https://ui.junxiong.dev/docs/deck.md): The deck player: one transition grammar (advance, morph, zoom), builds, the overview, the speaker and read views, keyboard and touch.
- [Deck player: Consulting](https://ui.junxiong.dev/docs/deck-consulting.md): Dense consulting slides and their charts: tracker, action title, panels, so-what, footnotes, bars, waterfall, stacked bars, lines, KPI tiles, Harvey tables and a 2×2.
- [Deck storytelling](https://ui.junxiong.dev/docs/deck-storytelling.md): Storyline templates, slide roles and the checks lintDeck runs on a deck's argument.
- [lintDeck rules](https://ui.junxiong.dev/docs/deck-lint-rules.md): Every check lintDeck runs on a deck's words, with its severity, generated from LINT_RULES.
- [Slide starters](https://ui.junxiong.dev/docs/presentations.md): Slide layouts with their speech notes, then a complete five-chapter narrative built from them.
- [3D animations](https://ui.junxiong.dev/docs/slides.md): Live 3D scenes with camera moves, animated flows and presentation controls.
- [3D object scenes](https://ui.junxiong.dev/docs/objects.md): Reusable, lazy 3D illustrations, their art directions and the player that shows them.
- [Mechanism](https://ui.junxiong.dev/docs/mechanism.md): Mechanical drawings that explain how a system moves, one part at a time.
- [Docs layout](https://ui.junxiong.dev/docs/docs-layout.md): A three-column product documentation shell with responsive navigation and Markdown prose.

## Component looks

- [Component looks](https://ui.junxiong.dev/docs/components/README.md): Each component's named looks, fixed (the same on every site) or flex (taking the site's palette and faces), and how a spec picks them.
- [Diagram look and themes](https://ui.junxiong.dev/docs/components/diagrams.md): The Blueprint look and diagram themes: one grammar on every site, colours, faces and ground from a theme; the theme API, the user-flow and sequence parts, the node strip.
- [3D looks](https://ui.junxiong.dev/docs/components/3d.md): The six 3D looks, which subjects offer each, and which one takes the site's palette.
- [Mechanism look](https://ui.junxiong.dev/docs/components/mechanism.md): The isometric machine look: its fixed drawing and the roles it takes from the site.

## Specs

- [How to write a spec](https://ui.junxiong.dev/docs/specs/README.md): One spec per website: its look, layout, writing style and component looks on top of the core rules; how to write and check one, and how it becomes a live style.
- [Spec template](https://ui.junxiong.dev/docs/specs/TEMPLATE.md): The file a new site spec starts from: the frontmatter (pages, layouts, component looks) and the sections the checker requires.
- [Technical](https://ui.junxiong.dev/docs/specs/technical.md): The uipack site's spec: Cyanotype, Prussian ink and one amber mark, IBM Plex, with its role values generated from the style file.
- [Registry](https://ui.junxiong.dev/docs/specs/registry.md): Every site uipack designs for: where its spec lives, the component looks it picks and the uipack release it pins.

## Examples

- [Example landing page](https://ui.junxiong.dev/docs/examples/landing-page.md): A landing page built with uipack/web in Technical, how it is built, and every part it is made of.
- [Example text page](https://ui.junxiong.dev/docs/examples/text-page.md): A documentation page written to the read-alone rules: how to check a deck before you present it.

## Reference

- [Icons & marks](https://ui.junxiong.dev/docs/icons-and-marks.md): Searchable icons, marks, canvas backgrounds and motion tokens, each with a preview and a copy button.
- [Contributing](https://ui.junxiong.dev/docs/contributing.md): Step-by-step recipes, with the exact files to touch, for a new style, page, deck, slide part, chart or figure.
- [Testing](https://ui.junxiong.dev/docs/testing.md): What the unit and browser suites check, how CI runs them and the known engine quirks.
- [Releases](https://ui.junxiong.dev/docs/releases.md): How a version is cut: semver for this repo, the changelog, the tag on main, and how each site moves its pin.
- [Component-first](https://ui.junxiong.dev/docs/component-first.md): Build, register and verify a significant visual in the library before a consumer uses it.
- [Design direction](https://ui.junxiong.dev/docs/design-direction.md): The playground's visual direction, catalog taxonomy, interaction polish and presentation composition.
- [Canvas and selection](https://ui.junxiong.dev/docs/interaction.md): Mobile reading, item selection, expanded inspection and their limits.
- [Web principles](https://ui.junxiong.dev/docs/web-principles.md): The numbered rules for uipack/web pages, each with its number and source, motion and backgrounds included.
- [Web parts API](https://ui.junxiong.dev/docs/web-api.md): The uipack/web parts with their props: page parts, motion, backgrounds, type and scoping.
- [Web principles: Smooth scrolling](https://ui.junxiong.dev/docs/web-smooth-scroll.md): How SmoothScroll eases the wheel on a landing page, what stays native, anchors and its API.
- [Web discoverability](https://ui.junxiong.dev/docs/web-discoverability.md): How a uipack/web page gets found and quoted by search and answer engines: the checklist and the crawler stance.
- [Web discoverability: Head and structured data](https://ui.junxiong.dev/docs/web-discoverability/head-and-structured-data.md): pageMeta, the head helpers, font preloads, the JSON-LD builders and the FAQ.
- [Web discoverability: Crawl files](https://ui.junxiong.dev/docs/web-discoverability/crawl-files.md): buildCrawlFiles for robots.txt, sitemap.xml and llms.txt, rssFeed, and Section lazyRender.
- [Web discoverability: Performance](https://ui.junxiong.dev/docs/web-discoverability/performance.md): Load and paint numbers measured on the /web demo, the method, and what changed each.
- [Portfolio ideas](https://ui.junxiong.dev/docs/portfolio-ideas.md): Prioritised places where uipack/web pieces would improve junxiong.dev, and what to avoid.

## Grading

- [How to grade](https://ui.junxiong.dev/docs/grading/README.md): How an agent grades its own UI work before handoff, and how a lead grades a subagent's: three tiers, values first.
- [Mechanical checks](https://ui.junxiong.dev/docs/grading/tier-1.md): The 13 deterministic checks, their thresholds and sources, the CLI, the report and the site config.
- [Pairwise judging](https://ui.junxiong.dev/docs/grading/protocol.md): Two fresh judges in opposite order compare A and B on one brief and a frozen rubric; the packet and the tally.
- [Calibration anchors](https://ui.junxiong.dev/docs/grading/calibration.md): Known human pages scored on the same rubric, so a target score reads relative to them.
- [Regression set](https://ui.junxiong.dev/docs/grading/regression.md): Fifteen frozen briefs reused every round, and the fix ledger that proves a fix reached the next build.
- [Grading docs for agents](https://ui.junxiong.dev/docs/grading/agent-docs.md): How to grade uipack's own docs for their agent readers: the mechanical check, task-based judging and the frozen tasks.
- [Landing rubric](https://ui.junxiong.dev/docs/grading/rubrics/landing-v1.md): Version 1 of the frozen judge rubric for landing pages.
- [Docs rubric](https://ui.junxiong.dev/docs/grading/rubrics/docs-v1.md): Version 1 of the frozen judge rubric for documentation and articles.
- [Deck rubric](https://ui.junxiong.dev/docs/grading/rubrics/deck-slide-v1.md): Version 1 of the frozen judge rubric for decks.
- [Dashboard rubric](https://ui.junxiong.dev/docs/grading/rubrics/dashboard-v1.md): Version 1 of the frozen judge rubric for dashboards.
- [Diagram rubric](https://ui.junxiong.dev/docs/grading/rubrics/diagram-v1.md): Version 1 of the frozen judge rubric for figures.
- [Agent docs rubric](https://ui.junxiong.dev/docs/grading/rubrics/agent-docs-v1.md): Version 1 of the frozen rubric for a documentation set read by agents: routing, progressive disclosure, index, executable rules, currency, stop conditions.

## Skills

- [Skills index](https://ui.junxiong.dev/skills/README.md): one skill per job; read the one for your job after docs/agents/README.md.
- [uipack-copy](https://ui.junxiong.dev/skills/uipack-copy/SKILL.md): Write or tighten the words of a UiPack piece: slide titles, points and speaker notes, a read-alone deck or document, landing and web copy, figure labels and captions.
- [uipack-diagram](https://ui.junxiong.dev/skills/uipack-diagram/SKILL.md): Draw a diagram in UiPack's Blueprint look: a system or architecture figure, a request flow, a before/after, a drill-down figure or a layered chart for a site, article, doc or slide.
- [uipack-page](https://ui.junxiong.dev/skills/uipack-page/SKILL.md): Build or restyle a page or deck with UiPack from its recipe: a landing or product page, a documentation or article page, a slide deck or talk, a dashboard, or a 3D hero or motion explainer on one of them.
- [uipack-review](https://ui.junxiong.dev/skills/uipack-review/SKILL.md): Review or grade a UiPack page, deck, figure or section before it ships or is handed off: the tier-1 mechanical grader, then a read against the site spec and the core rules, with findings by layer.
- [uipack-spec](https://ui.junxiong.dev/skills/uipack-spec/SKILL.md): Write, update or check a website's UiPack site spec (its STYLE.md): palette, faces, radii, ornaments, density, a layout per page type, writing style and component looks, from the template, checked by check-spec and listed in the registry.