webawesome-design

name	webawesome-design
description	Design and lay out user interfaces with Web Awesome. Use this when building or styling a PAGE, LAYOUT, or SECTION; choosing or customizing a THEME; applying brand COLORS or design tokens; or composing a polished, good-looking UI with Web Awesome components and utilities. Triggers on requests like "build a landing page", "make an app layout", "set up <wa-page>", "add a sidebar", "apply a theme", "match our brand color", "style this to look designed", "build a settings page", or "lay out a dashboard". Teaches layout (when and how to use <wa-page>), theming (--wa-* tokens), and visual composition. Pair with the `webawesome` skill, which documents individual component APIs.
license	MIT / Commercial (for Web Awesome Pro)
metadata	{"author":"Web Awesome","homepage":"https://webawesome.com"}
compatibility	Works in modern browsers. Requires no build tools when using the CDN. Works with bundlers like Webpack and Vite when installed via npm.

Designing with Web Awesome

This skill teaches you to design well with Web Awesome: how to lay out pages, theme them on-brand, and compose interfaces that look intentionally designed rather than merely functional. The single most important habit is to lean into Web Awesome's design system first — its components, layout utilities, tokens, and styling API — and reach for custom CSS only when the system genuinely doesn't cover the need (see "Use Web Awesome's design system first" below). For the API of any single component (props, slots, events), use the companion webawesome skill or llms.txt.

Read this file first. It routes you to the right reference and states the rules that matter most.

---

STEP 0 — Decide your layout strategy (do this first, every time)

Before writing any markup, answer one question: am I building a whole page, or a piece of one?

→ Building a full page, app shell, or site layout?

If you own the entire viewport (header, navigation/sidebar, main content, footer), use <wa-page>. It is the recommended, supported way to scaffold a full page in Web Awesome, and it gives you sticky headers, a responsive navigation drawer, and a correct grid with almost no markup.

Read references/layouts-page.md and follow its rules exactly.

⚠️ <wa-page> owns the layout — including the navigation. The navigation slot is special: you put your nav in slot="navigation" once, and the component renders it as a left sidebar on desktop and moves it into a mobile drawer (with a hamburger button it provides) below mobile-breakpoint. You do not wire up a drawer, a toggle, or media queries for any of this — it's automatic.

The #1 mistake is duplicating the nav: putting the same links in header and navigation (or copying them around) so they render twice. There is no "this copy is mobile, that copy is desktop" — slot="navigation" is already both. Write it once.

• App shell / docs / dashboard (you want a desktop left sidebar): Put nav in slot="navigation", set --menu-width, reset it to auto on mobile. The default hamburger or a data-toggle-nav element opens its drawer. Copy the canonical example in layouts-page.md.
• Landing page / marketing site: Simplest is to put nav in slot="navigation" anyway (sidebar on desktop, drawer on mobile — both free). If you specifically want nav in the header bar on desktop with no sidebar, use the "header on desktop, drawer on mobile" recipe in layouts-page.md — the one sanctioned, view-scoped way to duplicate nav. Either way, don't hand-roll your own <wa-drawer> or toggle. Copy the "Landing page" skeleton below.

→ Building a section, widget, card, form, panel, or embedding into a page you don't fully control?

Do NOT use <wa-page>. Reaching for it here causes broken layouts (it expects to own the viewport). Instead, compose with layout utilities: wa-stack, wa-cluster, wa-grid, wa-flank, wa-split, wa-frame. And because there's no <wa-page>, its features are unavailable here: no slot="…", no view='mobile', no --menu-width, no data-toggle-nav, and no .wa-desktop-only / .wa-mobile-only (those only work inside <wa-page>; use a CSS media query instead).

Read references/layouts-inpage.md.

The rule

Never mix the two at the same level. Don't nest <wa-page> inside another <wa-page>, and don't hand-roll a full-page grid when <wa-page> was the right tool.

Layouts nest, though. A full page contains sections, and every section is itself a piece-of-a-page — same for <wa-dialog> bodies, <wa-drawer> bodies, card contents, and any embedded panel. Inside those inner containers, you're back in the in-page branch (utility classes, no <wa-page> slot semantics) regardless of what the outer page is. Answer STEP 0 for the outermost frame; then answer it again for each self-contained inner container.

If you're unsure which branch applies, ask the user: "Are you building a full page, or a piece of one?" before generating markup.

---

Use Web Awesome's design system first (the core mindset)

Web Awesome is a complete, opinionated design system — components, layout utilities, design tokens, themes, and a styling API — designed so you rarely need to write custom CSS or build your own primitives. Your default is to understand what the system already provides and reach for it, not to invent. Custom code is the exception you justify, not the starting point.

Before you write a custom class, a raw flex/grid rule, a hardcoded value, or a hand-built component, work down this ladder and stop at the first rung that does the job:

1. A component. Is there already a <wa-*> for this (button, card, dialog, dropdown, input, tabs, …)? Use it instead of assembling the same thing from <div>s. Check the companion webawesome skill before building UI by hand. Watch for these commonly re-invented ones: a "featured/Most Popular" pricing tier is a <wa-card> with a <wa-badge> in its header slot (not an absolutely-positioned hand-rolled ribbon); a section separator is <wa-divider> (not a styled <hr>); a pill/label is <wa-tag> or <wa-badge>; a quote mark, check bullet, or star rating is <wa-icon> / <wa-rating> (not CSS ::before glyphs). If your markup is starting to look like a component, stop and use the component.
2. A layout utility. Need to arrange things? Use wa-stack, wa-cluster, wa-grid, wa-flank, wa-split, wa-frame (and <wa-page> for full pages) before reaching for hand-written flexbox/grid. (Modifier classes like wa-frame:landscape and wa-flank:end are real, supported syntax — not typos.)
3. A token. Need a color, space, radius, font size, shadow, or transition? Use the --wa-* token or wa-* utility from the scale — never a raw px/hex/rem literal. Don't re-alias an existing token into your own namespace (--brand-dark: var(--wa-color-orange-30)); reference the --wa-* token directly so re-theming still works. (See composition.md for token-based recipes for fixed-size elements — icon badges, avatars, content widths — so you're never tempted back to raw rem.)
4. The component's styling API. Need a component to look different? First look up that specific component's documented styling API — its attributes (variant, appearance, size, pill, …), its CSS custom properties (--wa-* it exposes), and its () — in the companion (or ). Then style through that API in this order: . Never guess a token name, a part name, or which token a resolves to, and never fight the shadow DOM with host CSS. This lookup is — see rule 9 below. (Also composition.md.)

If you catch yourself writing a hex color, a px value, a raw flexbox container, or re-implementing something that smells like an existing component, stop and look it up first. Most of the time the system already has it, and using it gives you theming, dark mode, accessibility, and consistency for free.

---

The rules that matter most

These are the things that go wrong most often. Treat them as hard constraints.

1. Custom elements never self-close. Always use a closing tag: <wa-input></wa-input>, never <wa-input />.

2. When using <wa-page>, reset html and body with html, body { min-height: 100%; padding: 0; margin: 0; }, or you'll get unexpected gaps. (Web Awesome's Native styles handle this for you; see theming.)

3. <wa-page> adds no semantic elements. Slot in your own <header>, <main>, <footer>, <nav>, <aside>.

4. Zero <main> padding for full-bleed pages. <wa-page> pads the main area, which insets hero and section backgrounds from the viewport edge. Set main { padding: 0 } and let each section own its gutter. Keep the default only for a single contained column. See references/layouts-page.md.

5. Never hardcode colors, spacing, radii, or font sizes. Use design tokens (--wa-color-*, --wa-space-*, --wa-border-radius-*, --wa-font-size-*) and utility classes (wa-gap-*). Raw px and hex values break theming and consistency.

6. Set a theme and palette on <html>. A page with no theme class looks unstyled. See references/theming.md.

7. Use the layout utilities instead of ad-hoc flexbox/grid CSS. wa-stack (vertical), wa-cluster (inline wrap), wa-grid (responsive columns). Pair them with companion utilities (wa-align-items-*, wa-justify-content-*, wa-text-*, wa-size-*, wa-color-text-*, wa-visually-hidden) for alignment, text, sizing, color, and accessibility — anywhere you'd otherwise reach for inline style="". See references/composition.md.

---

Final pass — verify your work before you finish (do this every time)

Producing the markup is the first draft, not the finished design. You must circle back and verify the output against this skill before declaring it done — every time. Models reliably state these rules and then violate them while generating long files; an explicit verification pass is what actually catches it.

This is the structural pass — markup, decisions, valid HTML, rule compliance. For visual quality (spacing rhythm, hierarchy, contrast, surface choices) walk the Polish checklist in composition.md too.

This verification is mandatory and has two parts:

1. Self re-read. Re-read the rules above and walk your own output line by line, fixing each item in the checklist below.
2. Independent subagent review (required). After your self-pass, dispatch one or more verification subagents to re-check the design independently — do not rely solely on your own review of work you just wrote. Give each subagent the produced markup/CSS and this skill's rules, and ask it to find violations and report or fix them. For a substantial page, split the work: e.g. one subagent audits the <wa-page> layout and the navigation-duplication trap, another audits tokens/emojis/accessibility. Apply whatever the subagents surface, then confirm the result is clean. Treat their findings as authoritative over your own first draft.

Walk this checklist (yourself, and via the subagents) and fix each before declaring it done:

• Duplicated <wa-page> nav (check this first on any full page). Search your markup for the same nav links appearing in more than one slot. slot="navigation" already renders in both views (sidebar on desktop, drawer on mobile), so a second copy elsewhere shows twice. The only allowed duplication is the deliberate "header on desktop, drawer on mobile" recipe, where each copy is hidden in the opposite view via wa-page[view='…']. If you find an accidental copy, delete it and keep the single slot="navigation". Also confirm you did not hand-roll a <wa-drawer> or toggle — the component provides both. See the landing-page skeleton above.
• Empty <wa-page> nav column band. Only set a fixed --menu-width when you actually render a desktop sidebar. If you hid the desktop sidebar via the header/drawer recipe (wa-page[view='desktop']::part(navigation) { display: none }), confirm --menu-width is left at its auto default — a fixed value (e.g. 14rem) reserves an empty band down the left side, because hiding the sidebar part does not collapse the menu grid track (only --menu-width does). The tell is "I added display: none but the gap is still there." Search for a fixed --menu-width paired with a hidden desktop sidebar and remove it.
• Raw values — search for # (hex), px, and stray rem. The only allowed hex is the :root brand-token override; everything else is a --wa-* token. (Sizing recipes: composition.md.)
• Repeated inline styles — if the same style="…" appears more than once, promote it to a class. Inline is only for genuinely one-off per-instance custom-property values.
• Hand-rolled display:flex/grid — if it has gap/align/, replace it with ////.

If you can, render the page and look at it (sticky regions not overlapping, secondary buttons readable on colored bands, no mobile nav bleeding into desktop, nothing clipped) and fix what you see.

---

Recommended starting points

Pick the skeleton that matches your STEP 0 answer. Each produces a complete, on-brand, responsive result out of the box. Free users: only use free themes (default, shoelace, or awesome). Pro users: swap in a Pro theme/palette if the user wants one (see theming).

Full page — landing / marketing (<wa-page>) — use this by default

Nav goes in slot="navigation" once. <wa-page> renders it as a sidebar on desktop and a drawer (with a hamburger) on mobile — no hand-rolled <wa-drawer>, no toggle, no media queries for the nav. This is the right skeleton for a hero-driven landing page, marketing site, or most content pages. (Want nav in the header bar on desktop with no sidebar? See the "header on desktop, drawer on mobile" recipe in layouts-page.md.)

<!doctype html>
<html lang="en" class="wa-theme-default wa-palette-default wa-light">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- Load Web Awesome here (see the webawesome skill for installation) -->
    <style>
      html,
      body {
        min-height: 100%;
        padding: 0;
        margin: 0;
      }
      main {
        padding: 0; /* let hero/section backgrounds run edge-to-edge */
      }
      .section {
        padding-inline: var(--wa-space-xl);
      }
      wa-page {
        --menu-width: 14rem;
      }
      wa-page[view='mobile'] {
        --menu-width: auto; /* collapse the reserved sidebar space on mobile */
      }
    </style>
  </head>
  <body>
    
      
        My Brand
      

      
      
        Features
        Pricing
        FAQ
        Get started
      

      
        
          Big headline
          Your hero content goes here.
          Get started
        
        
      

      
         My Brand
      
    
  

Full page — app shell / docs (<wa-page> WITH a desktop sidebar)

When you want a richer left sidebar on desktop with a header, footer, and a subheader (e.g. breadcrumbs). This uses navigation + navigation-header/navigation-footer, --menu-width, and an optional data-toggle-nav in the subheader. See the canonical example in references/layouts-page.md.

A section (utilities only, no <wa-page>)

<section class="wa-stack wa-gap-l" style="max-width: 32rem;">
  <h2>Contact us</h2>
  <wa-input label="Name"></wa-input>
  <wa-input label="Email" type="email"></wa-input>
  <wa-textarea label="Message"></wa-textarea>
  <div class="wa-cluster">
    <wa-button variant="brand">Send</wa-button>
    <wa-button appearance="plain">Cancel</wa-button>
  </div>
</section>

---

References

• principles.md: Design principles behind WA's tokens — hierarchy, spacing rhythm, typography, color discipline, depth, finishing moves, empty states. The why that makes the other references click. Read this when output looks correct but unrefined.
• layouts-page.md: Full-page layouts with <wa-page>. Read this for the full-page branch.
• layouts-inpage.md: Sections, widgets, and embeds with layout utilities. Read this for the in-page branch.
• theming.md: Themes, palettes, light/dark, semantic colors, and customizing with --wa-* tokens.
• composition.md: Spacing rhythm, the layout-utility decision guide, typography, surfaces, images/placeholders, and the custom CSS playbook (dark-mode-safe, contrast-aware). Read this to make things look designed.
• patterns.md: Ready-made, best-practice recipes (app shell, login, settings, dashboard grid, hero).
• getting-started.md: The opinionated default setup, explained.