Audit screen

When to use

You have HTML, CSS, JSX, or similar markup and want a structured review of how well it conforms to Malevich. Use this before merging code that touches the design system, before adopting code from external sources, or as a periodic health check on a page that has seen many small edits.

The output is not a rewrite — it's a report. For the rewrite, chain into the refactor-to-malevich prompt or the malevich-refactor skill.

The prompt

Fill in the placeholders and send the text below.

You are working in the Malevich design system. Before answering, read:

• llm-wiki/glossary.md
• llm-wiki/architecture.md
• packages/lint/ (the active rules)

Then load the malevich-audit skill.

I want you to audit the following code:

Code:

{{code}}

Context (where this code lives): {{context}}

Run the audit in six passes, in this order:

1. Tokens — find every raw value (hex, rgb, hsl, px, em, named color, duration, raw shadow); also flag any direct tier-1 reference (var(--palette-*), var(--scale-*)) from a component or app. Group repeated violations as one finding.
2. BEM — verify modifier syntax (.block.-modifier, never .block--modifier, never standalone .-modifier); flag any legacy .t-name tweak class (migrate to a data-{category} modifier).
3. Component identity — for each visible UI control, identify the Malevich component it should be; flag hand-rolled equivalents, custom elements, and role-on-div substitutes.
4. Composition — verify layer direction (primitive < element < block < section; overlays don't nest in overlays) is respected.
5. Accessibility — check semantic HTML, ARIA correctness, focus visibility, keyboard reachability.
6. Modifiers — if data-{category} modifiers are used, verify the category and value are in the component's row of packages/components/modifiers/applicability.json, that no two values of one category are stacked, and that any behavior modifier has a runtime to wire it.

Output the report in this exact shape. For each finding:

[severity] [pass] [file:line or context-anchor] short title
  what:    one sentence of what's wrong
  why:     one sentence of why, citing the rule
  fix:     the minimal change as code

Severities:

• blocker — would fail lint, breaks the contract, or introduces an accessibility regression
• major — works at runtime but violates conventions
• minor — stylistic only

End the report with:

• A count line: N blockers, N majors, N minors
• A one-line disposition: "Approve after blockers fixed" / "Request changes" / "Reject — recommend rewrite via refactor-to-malevich prompt"
• (Optional) a 1-2 sentence note on patterns that suggest systemic issues across the codebase, not just local fixes.

If you find no violations, say so plainly. Don't manufacture findings to fill a quota.

Variables

Example input

Context: header on the public landing page (PR #87, adding a "Pricing" link).

<header class="site-header" style="background: #000; padding: 24px 32px;">
  <a href="/" class="logo"><img src="/logo.svg" alt=""></a>
  <nav>
    <a href="/components" class="nav-link">Components</a>
    <a href="/pricing" class="nav-link nav-link--new">Pricing</a>
    <a href="/manifesto" class="nav-link">Manifesto</a>
  </nav>
  <button class="btn-primary" onclick="signup()">Sign up</button>
</header>

Example output

[blocker] [tokens] inline:1 raw background and padding on header
  what: `style="background: #000; padding: 24px 32px"` uses raw values.
  why:  raw values are forbidden outside the token sources
        (malevich/no-raw-values); inline styles also bypass the cascade layer.
  fix:  Move to CSS using `var(--color-surface-canvas)` and
        `var(--space-inset-block-m) var(--space-inset-block-l)`.
        Remove the inline `style` attribute.

[blocker] [accessibility] inline:3 logo image has empty alt
  what: `<img src="/logo.svg" alt="">` marks the logo as decorative.
  why:  the logo is the only text identifier; screen readers won't announce it.
  fix:  `<img src="/logo.svg" alt="Malevich">`.

[major] [bem] inline:6 double-dash modifier
  what: `.nav-link--new` uses double-dash modifier syntax.
  why:  Malevich uses short-form leading-dash modifiers
        (malevich/bem-short-modifier).
  fix:  `.nav-link.-new`. (Better: use a Badge to mark "new" rather than
        modifying the link.)

[major] [component-identity] inline:8 hand-rolled button class
  what: `.btn-primary` is a hand-rolled equivalent of Malevich Button.
  why:  the system provides `.button.-accent` for primary actions.
  fix:  `<button class="button -accent">Sign up</button>`.

[major] [accessibility] inline:8 inline onclick handler
  what: `onclick="signup()"` couples markup to JS at the attribute level.
  why:  blocks CSP, breaks server-rendered hydration, and is a smell in
        modern markup.
  fix:  Remove `onclick`; bind via `addEventListener`, or use a form
        `<button type="submit" form="signup">`.

[minor] [component-identity] inline:1 reimplemented site chrome
  what: `.site-header` here is hand-rolled, duplicating the Site-header section.
  why:  the Site-header section gives consistent spacing, the `sticky`
        behavior modifier, blur effect, and theme switching.
  fix:  Adopt `<header class="site-header">` per the Site-header docs;
        opt into stickiness with `data-behavior="sticky"`.

---

2 blockers, 3 majors, 1 minor

Request changes. Block the merge until the two blockers are fixed.

Note: this header was likely hand-rolled before the Site-header section
existed. The same pattern probably exists on other pages — worth a
system-wide grep for hand-rolled headers.

Tips

• Don't paste an entire page. Audit one region at a time; the per-finding output gets hard to act on otherwise.
• Include context. "This is the checkout button" tells the agent whether -accent or a status treatment is more appropriate.
• Re-run after fixes. A clean audit is the proof the refactor worked. The pass becomes the merge gate.

Pairs with

• Skill: malevich-audit — the procedural skill this prompt invokes.
• Prompt: refactor-to-malevich — chain into this if the report comes back with majors/blockers and you want a rewrite proposal.