Aura Review

Aura Review

An objective, code-level audit of Aura usage in a generated app: did the app use Aura where Aura applies, and did it use the Aura components it did reach for correctly?

This skill never asks the user anything. It is designed to run unattended — inside a CI job on a nightly schedule, or by hand — and to always finish with a report and a machine-readable stats file.

The one rule that matters more than any step below

Only flag something as wrong if it is already written down in either DESIGN.md or the public Aura docs. If you notice something that feels wrong but isn't documented anywhere, do not invent a rule to justify flagging it, that isn't a fair test of an app built against documentation that never mentioned the rule. Instead, note it as a suggestion for the docs and move on. This matters because these reports get used to tell people "Aura says you did X wrong" — that claim has to be traceable to something they could have read.

Likewise, when judging whether a custom component "could have been Aura", only say so when you can point at a specific Use when bullet for a named Aura component that matches — otherwise mark it undecided rather than guess.

Sources of truth (v1, Storybook is deliberately out of scope for now)

Both docs URLs above are trusted, so fetch them with WebFetch directly rather than curl (curl requests to them get denied).

Do not reach for Storybook yet. It's excluded from this skill until we have a reliable index of story code (index.json / per-story JSON work).

Step 0 — locate the app and confirm prerequisites

Resolve <app-dir> from $ARGUMENTS, or default to the current directory. Print the resolved absolute <app-dir> path before doing anything else — if $ARGUMENTS was empty and this silently defaulted to the current directory, that's the only signal a user gets that they may be auditing the wrong app.

Confirm <app-dir>/node_modules/@cognite/aura/package.json and <app-dir>/node_modules/@cognite/aura/DESIGN.md both exist — if not, stop and report that npm/pnpm install needs to run first (this skill never installs dependencies itself).

Step 1 — run the objective scan (script, not you)

This is the part that must be deterministic, so it's a script, not something you eyeball. The script requires typescript, which lives in <app-dir>'s own node_modules (any Vite/TS scaffold has it as a devDependency) rather than next to this skill — set NODE_PATH so Node's resolver finds it there instead of copying the script into the app:

NODE_PATH="<app-dir>/node_modules" tsx <this-skill-dir>/scripts/scan-aura-usage.ts <app-dir> --out aura-review/scan.json

If tsx isn't on PATH, fall back to npx --yes tsx ... (prefer the direct binary when available — npx has been observed to resolve a stale cached path to tsx's own CLI entrypoint in some environments).

Read the resulting aura-review/scan.json. It contains:

• availableAuraComponents — Aura's full component catalog (Pascal case, e.g. Card, Accordion, ...), from the installed @cognite/aura version. Not used in this run's coverage math — kept so a future aggregate step (across many scans) can compute catalog utilization, i.e. which Aura components barely get used anywhere. See the auraCoveragePct note below for why that's a different question than this run's coverage number.
• auraUsages / nonAuraUsages — distinct component types, one entry per identifier, each with usageCount and every occurrence's locations. auraUsages only counts root-level Aura tags (e.g. Card, Button) — compound/slot sub-components (CardContent, CardHeader, AlertDescription, ...) are folded into their parent's usage, not counted as separate component types, because a Card composed of five slots is one usage of Card, not five usages of the design system. nonAuraUsages entries are tagged with importSource (relative, external, or unresolved-local for components defined in the same file) — this covers both first-party components the app built and third-party ones it chose instead (icons, react-router-dom, providers, etc.).
• excludedUsages — framework/router noise (Route, Link, Fragment, ...) and namespaced tags (React.StrictMode, property access on a namespace import, not a component the app authored). Excluded from every list and count above, kept here purely for transparency — nothing is silently dropped.
• totals.auraCoveragePct — auraUsages.length ÷ (auraUsages.length + nonAuraUsages.length) (the distinct-count lists, not the all* occurrence lists): of the different kinds of components this app reached for, what fraction were Aura. Deliberately not occurrence-based — a component reused many times would otherwise dominate the ratio and overstate coverage relative to how many different kinds of components the app actually used. Also deliberately not divided by availableAuraComponents.length — that would conflate "how many components did this app need" with "did it use Aura where it mattered" (a small app needing only 3 components would cap out far below 100% even with perfect compliance). totals.allAuraUsages / totals.allNonAuraUsages report raw occurrence counts alongside this, as context, but are not what coverage is based on.
• escapeHatches — every Aura component usage, including sub-components, whose className raw Tailwind values look like spacing, color, or arbitrary-value overrides. This is a purely mechanical regex check; it is not yet a verdict — some of these will turn out to be legitimate per Step 4.

Step 2 — report the coverage number as-is

auraCoveragePct from Step 1 goes straight into the report and stats.json, with the caveat above about what it does and doesn't count. Do not adjust it — it's meant to be a stable, comparable number across runs so KCIH-1222/1223 can track it over time. Judgment happens in the two steps below, as separate numbers.

Step 3 — judge non-compliance (this is where you read DESIGN.md)

For each entry in nonAuraUsages whose importSource is relative or unresolved-local (i.e. first-party — skip external entries, they're a deliberate choice unrelated to Aura, not a compliance signal):

1. Open its first usage location and skim enough surrounding JSX to understand what the component actually renders/does.
2. Search DESIGN.md's "Primitive guidance" component entries (grep for plausible component names, or read the whole section if it's short enough) for one whose "Use when" bullets match this component's apparent purpose.
3. If you find a specific match, record { identifier, couldHaveBeenAura: "<ComponentName>", evidence: "<quoted Use when bullet>" }.
4. If DESIGN.md doesn't cover it, WebFetch the matching Primitives page on https://docs.cognite.com/aura-design-system (per DESIGN.md's own "Docs reference" URL pattern) or check https://cognitedata.github.io/flows-community-components/ the same way before giving up.
5. If none of those sources support a specific match, record { identifier, couldHaveBeenAura: null } — do not guess.

couldHaveBeenAuraPct = (# entries with a non-null couldHaveBeenAura) ÷ (total entries considered, i.e. couldHaveBeenAuraConsideredCount). Report the count either side of that ratio, not just the percentage — a percentage over 2 components reads very differently than over 20.

Also report couldHaveBeenAuraOfNonAuraPct = (# entries with a non-null couldHaveBeenAura) ÷ nonAuraUsages.length (the full distinct non-Aura population from the scan, including external entries this step deliberately skipped). This is a secondary, broader-context number — it's expected to read lower than couldHaveBeenAuraPct whenever the app has legitimate third-party usage, since that usage counts in this denominator but was never a compliance candidate. Don't use it in place of couldHaveBeenAuraPct; the considered-only ratio above is still the fair compliance signal.

Step 4 — judge documented usage-quality findings

For each entry in escapeHatches, and separately for any Aura component used unusually heavily (e.g. hand-composing many raw sub-elements around it), check DESIGN.md's entry for that component's slug — and, if it doesn't cover the point, the matching page on https://docs.cognite.com/aura-design-system — for a specific "Dos and don'ts" or "Behavior" line the usage contradicts.

• If you find one, record the finding with the exact quoted rule it violates.
• If you don't, drop the escape-hatch finding from the final report — a raw Tailwind override that the docs don't actually forbid for that component isn't a usage-quality problem, it's just a mechanical hit that didn't hold up.

This step is deliberately the most expensive per-finding — it's also the one guarding against the exact failure mode called out in review: don't grade an app against knowledge the model has but the docs don't.

Step 5 — write the outputs

Write aura-review/report.md:

# Aura Review — <app-dir>

## Headline numbers

- Aura coverage: <auraCoveragePct>% (<auraUsages> / <totalUsages> distinct component types; <allAuraUsages> / <allAuraUsages + allNonAuraUsages> raw occurrences)
- Could have been Aura: <couldHaveBeenAuraPct>% (<n> / <total> custom components had a documented Aura equivalent; <couldHaveBeenAuraOfNonAuraPct>% of all non-Aura usages)
- Documented usage-quality findings: <count>

## Non-compliance findings

| Component | Usages | Could have been | Evidence |
| --------- | ------ | --------------- | -------- |
| ...       | ...    | ...             | ...      |

## Usage-quality findings

| Aura component | File:Line | Violates | Quoted rule |
| -------------- | --------- | -------- | ----------- |
| ...            | ...       | ...      | ...         |

## Excluded from judgment (third-party, not a design-system concern)

- <identifier> (<count> usages, from `<package>`)

Write aura-review/stats.json — this is what a future upload-to-CDF step consumes, so keep the field names stable:

{
  "auraCoveragePct": 0.62,
  "auraUsages": 8,
  "nonAuraUsages": 5,
  "allAuraUsages": 18,
  "allNonAuraUsages": 11,
  "couldHaveBeenAuraPct": 0.25,
  "couldHaveBeenAuraCount": 2,
  "couldHaveBeenAuraConsideredCount": 8,
  "couldHaveBeenAuraOfNonAuraPct": 0.4,
  "usageQualityFindingsCount": 3
}

Step 6 — print a one-line summary

Print to stdout, so a CI log shows the result without opening any file:

aura-review: coverage=<auraCoveragePct>% could-have-been-aura=<couldHaveBeenAuraPct>% (<n>/<total>) usage-quality-findings=<count>