` or raw `px` value gives one of those back. For the API of any single component (attributes, slots, parts, tokens), read the companion `webawesome` skill (`references/components/.md`) or [llms.txt](https://webawesome.com/docs/ai/). This file is a workflow plus the short list of things that go wrong most often. Detail lives in `references/`, linked where you need it. --- ## Workflow ### 1. Discover what the project already decided Most "the agent ignored our design system" failures are really "the agent never looked." In an existing project, spend a minute finding the decisions that are already made before you write markup or CSS: - The classes on `` (`wa-theme-*`, `wa-palette-*`, `wa-brand-*`, `wa-light`/`wa-dark`) and the stylesheet that overrides `--wa-*` tokens. That file **is** the project's theme; add to it, don't compete with it. - House recipes: project classes, wrapper components, and repeated `wa-*` compositions (a `.stat-card`, a ``, the way every form is laid out). Reuse them before reaching for a raw component. - A design brief the team keeps for agents (`DESIGN.md`, a design section in `AGENTS.md`/`CLAUDE.md`). - How existing pages handle layout, nav, and spacing. Match them. Precedence: **project conventions > this skill's defaults > your own taste.** On a greenfield project with nothing to discover, use the opinionated defaults in [getting-started.md](references/getting-started.md). How to search a project quickly, where customizations belong, and how to extend the system without forking it: [your-design-system.md](references/your-design-system.md). ### 2. Pick the layout branch Answer one question before any markup: **am I building a whole page, or a piece of one?** - **A full page, app shell, or site layout (you own the viewport)** → use ``. It provides the grid, sticky regions, and a responsive nav drawer. Nav goes in `slot="navigation"` **once**; the component renders it as a desktop sidebar and moves it into a mobile drawer with its own hamburger. Don't write a second copy of the nav, a ``, a toggle, or media queries for any of that. Read [layouts-page.md](references/layouts-page.md) and copy its canonical example. There is exactly one sanctioned second copy — the header-on-desktop / drawer-on-mobile recipe in that file, where each copy is hidden in the view it doesn't belong to. Use that recipe as written or don't duplicate at all. - **A section, widget, card, form, panel, or an embed into a page you don't control** → no ``. Compose with `wa-stack`, `wa-cluster`, `wa-grid`, `wa-flank`, `wa-split`, `wa-frame`. `` features (slots, `view`, `--menu-width`, `data-toggle-nav`, `.wa-mobile-only`) do nothing here; use a media query for responsive visibility. Read [layouts-inpage.md](references/layouts-inpage.md). Layouts nest: a full page contains sections, and every section, dialog body, drawer body, and card body is back in the in-page branch. Answer the question for the outermost frame, then again for each self-contained inner container. If you genuinely can't tell which branch applies, ask the user. ### 3. Build with the system, in this order Before writing a custom class, a raw `flex`/`grid` rule, a literal value, or a hand-built component, walk down this ladder and stop at the first rung that does the job: 1. **A project recipe** (from step 1), if one exists. 2. **A component.** Is there a `` for this? Use it instead of assembling the same thing from `

`s. Commonly re-invented: a "Most Popular" pricing ribbon is `` with a `` in its header slot; a section rule is ``; a pill is `` or ``; a check bullet, quote mark, or star is `` or ``. Unsure which component fits? The `webawesome` skill's `choosing-components.md` is a decision tree by intent. 3. **A layout utility.** `wa-stack`, `wa-cluster`, `wa-grid`, `wa-flank`, `wa-split`, `wa-frame`, plus the companion utilities (`wa-gap-*`, `wa-align-items-*`, `wa-text-*`, `wa-color-text-*`) before any hand-written flexbox or grid. (Modifiers like `wa-frame:landscape` and `wa-flank:end` are real syntax.) 4. **A token.** Every color, space, radius, font size, shadow, and transition comes from `--wa-*`. No hex, `px`, or stray `rem`. Reference tokens directly; don't re-alias them into your own names. 5. **The component's styling API.** To make a component look different: its attributes (`variant`, `appearance`, `size`, `pill`) → its own `--wa-*` custom properties → its documented `::part()`. Look the component up first; you cannot guess parts, tokens, or how a `variant` resolves to colors. 6. **Extend.** Only when the system genuinely doesn't cover the need, write a small amount of custom CSS built on tokens, following the [Custom CSS playbook](references/composition.md#custom-css). Extending the system a little is fine; replacing it or building a parallel design language is not. If you catch yourself typing a hex color, a `px` value, a bare `display: flex`, or markup that is starting to look like an existing component, stop and look it up. The system almost always has it. ### 4. Verify before you finish Run the checks in [Verify before you finish](#verify-before-you-finish) below. Producing the markup is the first draft; models reliably state these rules and then violate them while generating a long file, and an explicit pass is what catches it. --- ## What is fixed, and what is yours to decide - **Fixed (follow exactly):** token names and scales, component choice and their styling API, `` slot semantics, the project's discovered conventions. - **Yours (use judgment):** composition and hierarchy, which recipe fits, where on the spacing scale a gap belongs, copy, and how bold to be with color. [principles.md](references/principles.md) explains the design judgment the tokens encode; read it when output is correct but unrefined. --- ## The rules that matter most Each row names the mistake, the replacement, and why it matters. The "why" is there so you can apply the rule to cases the table doesn't list. | Instead of… | Do this | Why | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `` | `` | Custom elements never self-close; the parser swallows everything after the slash. | | Hex, `px`, or `rem` literals | `--wa-color-*`, `--wa-space-*`, `--wa-border-radius-*`, `--wa-font-size-*`; `wa-gap-*` classes | Literals ignore the theme, dark mode, and `--wa-*-scale` knobs. Only allowed hex: a brand override. | | `display: flex; gap: 16px` by hand | `wa-stack`, `wa-cluster`, `wa-grid`, `wa-flank`, `wa-split` + `wa-gap-*` | Utilities carry the spacing scale and sensible defaults; ad-hoc flex drifts from them. | | `style="…"` repeated across elements | A named class in a ` ``` --- ## References Read the one that matches the job; each is self-contained. - **[your-design-system.md](references/your-design-system.md):** Building a project's design system on Web Awesome. How to discover existing decisions, where customizations live, how to extend without forking, and a `DESIGN.md` template for teams. Read this in any existing project, and whenever asked to "match our design system." - **[layouts-page.md](references/layouts-page.md):** Full-page layouts with ``: mental model, the nav rules, canonical examples, checklist, API summary. Read this for the full-page branch. - **[layouts-inpage.md](references/layouts-inpage.md):** Sections, widgets, and embeds with layout utilities. Read this for the in-page branch. - **[theming.md](references/theming.md):** Themes, palettes, light/dark, brand color, and customizing with `--wa-*` tokens. - **[composition.md](references/composition.md):** Spacing rhythm, the layout-utility decision guide, companion utilities, typography, icons, images, surfaces, the Custom CSS playbook, styling components through parts, and the Polish checklist. Read this to make things look designed. - **[principles.md](references/principles.md):** The design judgment behind the tokens: color discipline, depth, hierarchy, spacing, type, finishing moves, empty states. Read this when output looks correct but unrefined. - **[patterns.md](references/patterns.md):** Ready-made recipes: app shell, landing page, login, settings, dashboard grid. - **[getting-started.md](references/getting-started.md):** The opinionated default setup for greenfield work.