> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required. # Frontend Quality Bar — Render Layout Tokens with Real Library Primitives > **Load this BEFORE writing any frontend page or component.** Read during **Step 1** (Frontend Preview) and **Step 12** (Wire Frontend). This is the contract between the plan's Section 6 (Design System & UI) and the scaffolded JSX. --- ## Shared design-quality principles (fidelity-agnostic — the contract BOTH phases share) > **This section is the single design-quality contract read by _both_ rendering targets:** > - **Planning preview** (`azure-project-plan`) — renders these principles as **raw, static HTML/CSS** in `.azure/.preview-temp/` (no framework, no build step, no JavaScript, no network). See the raw-HTML/CSS rendering recipes in [`html-preview.md`](.github/agents/azure-project-plan/references/html-preview.md). > - **Scaffold app** (`azure-project-scaffold`) — renders the *same* principles with the **real `Component Library` primitives** from Section 6, using the per-library mapping in the rest of this file, and adds the production-only capabilities the static preview cannot show (real photos, motion, dark mode, webfont, library elevation). > > Both targets must look like the **same professional product** at two fidelities. The planning preview is **not** a throwaway wireframe — it is a presentation-quality visual specification. The scaffold reproduces it faithfully and must **never regress below it**. Whatever the rendering target, every page MUST satisfy these six principles: 1. **Presentation quality, not a sketch.** Balanced spacing rhythm, real depth (a multi-tier elevation scale — not a single flat border), consistent corner radius, a coherent themed palette, clear typographic hierarchy, and realistic populated content. The bar is "a screen a designer would show a stakeholder to sign off the look", never a gray boxy wireframe. 2. **Theme from the brand color.** Derive the whole palette from Section 6's `primary` (plus `accent`/surfaces/text/muted/border). The planning preview expresses these as `:root` CSS custom properties; the scaffold wires them through the library's theme provider. Never ship the library's default brand color or hard-coded hexes in markup. 3. **Render layout tokens as real structure.** A `header + hero + grid + footer` layout is real regions with real content — never raw placeholder `
`s. (Raw HTML/CSS renders styled semantic elements; the scaffold renders real library primitives per the mapping below.) 4. **All four data states, at least once across the page set.** `data` (populated), `loading` (skeleton), `empty` (illustration/icon + call-to-action), `error` (inline banner + retry). The scaffold makes them reachable live via the Mock State Switcher; the planning preview depicts them statically. 5. **Real iconography.** Named icons with consistent stroke weight — inline `` in the static preview, the library's official icon set in the scaffold. **Never** emoji, Unicode glyphs, or `viewBox="0 0 1 1"` placeholder shapes. 6. **Every image slot is filled.** No empty tinted boxes. The static preview uses **neutral placeholder blocks** (a subtle surface + border with a muted icon or initials) — **not** brand-color gradients, which overstate how much the palette actually drives the design; the scaffold binds real image URLs from the mock data. > **Fidelity boundary — what only the scaffold does.** The static planning preview intentionally stops at what raw static files can do well: it uses **system fonts** (no remote webfont), **no JavaScript** (so no working theme toggle, no live state switching — states are depicted statically), and **neutral image placeholders** (no real photos). The scaffold adds real webfonts, motion, working dark mode, live four-state switching, and real imagery. That gap is the scaffold's value-add — it is **not** license for the planning preview to look unpolished. --- ## Core principle > **Layout tokens are layout INTENT, not implementation.** When the plan's Section 6 says a page's layout is `header + hero + grid + footer`, that does NOT mean produce four `
`s with placeholder text. It means **render the equivalent of those regions using the real `Component Library` named in Section 6, themed by the Section 6 Color Palette.** If you ever emit JSX like this: ```tsx // ❌ ZERO-EFFORT WIREFRAME REPRODUCTION — DO NOT SHIP
Header
Hero
Card 1
Card 2
``` …you have failed the quality bar. That output **looks worse than the presentation-quality plan preview** the user already approved, because it strips the theme, the icons, the elevation, and the state coverage the preview shipped. The preview is a promise; this contract is how you keep it. --- ## Section 6 inputs you MUST consume | Field in plan §5 | What it controls | |--------------------------|--------------------------------------------------------------------------| | `Component Library:` | Which library's primitives you import and render (mandatory). | | `Style Direction:` | Density, corner radius, elevation, list-vs-hero bias. | | `Typography:` | Font family applied at the app shell level. | | Color Palette table | Brand ramp / theme tokens — wire through the library's theme provider. | | Pages table (`Layout`) | Which **library primitives** to compose per page (see mapping below). | | `.azure/.preview-temp/*.html` + `theme.css` | The **presentation-quality static HTML/CSS preview** the user approved during planning. It is a faithful visual spec: page regions and order, the themed palette, real inline-SVG icons, populated content, and all four data states. What it deliberately omits (raw-static limits): real webfonts, motion, working dark mode, and real photos. **Reproduce it faithfully with real library primitives and add only those production-only capabilities** (see "Polish floor" below) — never regress below it. Do not import, embed, or `