Ng Styling

ng-styling

Styling rot is different from logic rot. CSS has no type system: the compiler won't catch a leaked framework class, an !important arms race, a raw hex color that should have been a design token, or a ::ng-deep reaching into a child component. Specificity creep and global leakage make every visual change risky and the styling layer hard for an AI agent to reason about – the same way any makes TypeScript hard. Scoped styles, design tokens, shallow selectors, and a clear global-vs-component split keep the CSS small, predictable, and safe to change.

This skill audits the styling of an Angular project against three sources of truth, writes a provenance-tagged, severity-ranked report, and – only on your approval – fixes findings in small, verified, checkpointed batches. The audit is the default; fixing is opt-in. Because styling changes can change what the user sees, the bar here is appearance-preserving, not merely behavior-preserving: every fix that can shift specificity or layout must be eyeballed.

Three sources of truth (cited on every finding)

Each finding carries the source(s) that back it, so you can trust and trace it:

The [repo] guide is the project's law and the most specific; [angular.dev] is the upstream backstop (it is deliberately thin on CSS – strong on the binding rule, encapsulation, file naming, and view transitions); the [deck] supplies topics the written guide under-emphasizes (encapsulation trade-offs, view transitions, component frameworks, design systems, inject(DOCUMENT)).

Note: the deck itself is not loadable in-context, so where a [deck] rule also has an official page – notably view transitions and View Encapsulation – prefer [angular.dev] (plus [repo]) as the citable, verifiable backing.

What it audits

Core – pass/fail against rules. Full catalog with detection and fixes in references/styling-checklist.md.

Advisory – opportunities, not violations. Reported separately; never auto-applied. Detail in references/component-frameworks.md.

• inject(DOCUMENT) for SSR-safe document access (scroll, body class). The write side (sanitization, raw DOM) defers to ng-security. [deck]
• View transitions – provideRouter(routes, withViewTransitions()); transition CSS (::view-transition-old/new, view-transition-name) must live in global styles, since encapsulation would scope it away. [deck] [angular.dev]
• Design systems & frameworks – detect the Tailwind v4 setup first: look for src/tailwind.scss, .postcssrc.json, and oklch tokens in src/styles.scss (the workshop's teaching branches don't have it yet; the demo branch does). While it's absent, treat Tailwind as to-be-configured and report adoption as the opportunity; once wired, audit the existing usage: check @layer order and the token-vs-utility split (design decisions live in CSS custom properties; utilities carry layout/spacing), and flag utilities that should have been a token. Plus the Material CDK for a11y, Storybook, Standalone + OnPush, and ViewEncapsulation.None for a design-system library ([angular.dev]); and consider adding Stylelint to make the mechanical rules deterministically enforceable. [deck]

Severity (mirrors the style guide)

Enforcement: tool-agnostic reasoning

This skill adds no tooling dependency. It reasons against the three sources using only what the project already has – Prettier (SCSS formatting) and ESLint (template binding & a11y rules). It does not require or install Stylelint; "add Stylelint" is an advisory finding only. The consequence: most SCSS-architecture rules are caught by reading and reasoning, not by a linter – so the report is the checklist, and the reference catalog tells you exactly what to look for.

Workflow

1. Inventory & scope

Default scope is the whole project; accept a narrower scope (a path, a component, a feature, or "global styles only"). Inventory:

• every *.scss (component styles, src/styles.scss, src/styles/ partials),
• inline styles/styleUrl(s) and encapsulation in @Component decorators,
• templates with ngClass / ngStyle / [class.*] / [style.*] / style="…",
• global vs component placement, and any component-framework usage (ag-grid, ng-select, spartan; Material/PrimeNG only if present).

2. Audit

Walk each of the 8 core categories against references/styling-checklist.md; collect advisory opportunities separately. For each finding record: severity · rule id · sources · file:line · what's wrong · suggested fix · fixable = auto | proposed.

3. Report

Write a grouped markdown report to styling-audit.md at the project root (path overridable), and render the same grouped summary in chat. Group by category; lead with 🔴 Must, then 🟡 Should, then 🔵 Advisory; end with counts and a suggested fix order. The run stops here unless you ask for fixes.

4. Fix on approval

Only after you say go. Apply in small batches, each batch one coherent kind of change:

• Mechanical (auto-applied per batch): ngClass → [class.x], ngStyle → [style.x], @import → @use/@forward, unitless 0, leading 0, shorthand – i.e. the unambiguous, low-risk rewrites.
• Judgment-heavy (proposed as diffs, you decide): changing encapsulation, extracting design tokens, removing !important / ::ng-deep (specificity risk), un-leaking framework classes, flattening deep nesting, restructuring global vs component styles.

Verify and checkpoint after every batch (see the gauntlet). Never stage, commit, or push.

5. Verify & review

Run the gauntlet on each batch and read the diff top-to-bottom. Confirm each change earned its keep (less complexity / clearer responsibility / closer to the guide) and that appearance is preserved – for any specificity- or layout-affecting change, verify visually. Re-audit the touched scope; the report should now be green there.

The gauntlet

After every fix batch, run in order and don't proceed until green:

build → lint → formatting check → test (if templates changed) → visual check (if appearance could shift)

Resolve commands from package.json (here: pnpm build, pnpm lint / ng lint, pnpm exec prettier --check ., pnpm test --watch=false). build catches SCSS compile errors and the anyComponentStyle budget; lint covers the template-binding rewrites; format is Prettier on SCSS. The visual check is unique to styling: unlike a behavior-preserving TS refactor, removing !important, changing encapsulation, or flattening selectors can change what renders.

Guardrails (non-negotiable)

• Appearance-preserving, not just behavior-preserving. CSS changes can alter the rendered result. Treat specificity/layout-affecting fixes as risky; verify visually; never bundle them blindly. Color-contrast and focus-visibility belong to ng-accessibility.
• Audit first; fixing is opt-in. A run is read-only until you approve fixes.
• Treat the agent like a junior. A human reviews every diff before commit. "Done" means the diff was read, not that the agent said so.
• No big-bang restyle. Small, reviewable, single-purpose batches – never a sweeping CSS rewrite.
• Every change earns its keep. Each edit must deliver less complexity, clearer responsibility, or closer conformance. A "fix" with no benefit isn't one.
• Preserve meaning. Keep meaningful comments and documented hacks/workarounds (the guide asks you to document complex CSS, not delete it). Don't change selectors that other code depends on without tracing usage.
• Advisory ≠ violation. Never auto-apply advisory items; present them and let the human choose.
• Git discipline. Start from a clean working tree; checkpoint after each batch. Never stage, commit, or push – surface the diff and let the human commit.

Setup this skill assumes

The workshop's quality frame should already be in place (see Lab 01): Prettier + ESLint, an AGENTS.md with the project rules, the project's style-guide/, the Angular MCP for current docs, and per-tool secret-deny rules (.claude/settings.json, .codex/config.toml). Stylelint is optional – if absent, the skill reports it as a 🔵 advisory rather than relying on it.

Pairs with

• ng-migrate – its Modernize step already migrates ngClass/ngStyle → bindings; run ng-styling for the SCSS-architecture and token work it doesn't cover.
• ng-accessibility – color contrast, focus rings, reduced-motion for view transitions.
• ng-performance – the anyComponentStyle budget, critical CSS, framework-CSS weight.
• ng-security – inline styles as a CSP concern; the write side of document access.
• ng-review-architecture – deeper structural review when a restyle turns into a design-system decision.
• spartan – when styling is built on spartan/ui (Helm) instead of a heavy component framework.

Detailed references

• references/styling-checklist.md – the full, provenance-tagged rule catalog: every rule with its id, severity, sources, how to detect it, the fix, and whether it's auto- or proposed-fixable.
• references/scss-architecture.md – global vs component split, the global-styles layer order, @use/@forward migration, design tokens vs :host knobs, the View Encapsulation decision guide, specificity & nesting, logical properties, and where view- transition CSS must live.
• references/component-frameworks.md – the heavy-CSS frameworks to detect in package.json (ag-grid .ag-*, ng-select .ng-*, spartan; Material/PrimeNG as a generic aside) and how to customize without leaking their classes, design-system best practices, the inject(DOCUMENT) advisory, and "consider Stylelint".

Origin

Authored in this repository from Alexander Thalhammer's workshop deck "Angular Styling", this project's style guide, and the official Angular style guide. MIT-licensed.

Verification contract

Use the repository VERIFICATION.md when present. Run checks independently on the final files so a known-red baseline cannot suppress later results. Autofix and formatting writes belong to implementation; reverify after them. Compare exact baseline diagnostics and run the relevant behavior tests explicitly.