ng-styling
Skill13 starsChanged 44 days agoMITView on GitHub
Audit Angular styling against the repo style guide, the "Angular Styling" workshop deck, and angular.dev, then fix findings on approval. Use when reviewing, checking, or cleaning up Angular styling / CSS / SCSS: prefer `[class.x]` / `[style.x]` over `ngClass` / `ngStyle`, View Encapsulation (Emulated / ShadowDom / None), (S)CSS architecture, design tokens via CSS custom properties and `:host` knobs, BEM with a project prefix, nesting depth, and removing `!important`, `::ng-deep`, `float`, inline styles, and leaked framework classes (ag-grid `.ag-*`, ng-select `.ng-*`, spartan). Also advises on SSR-safe DOM access, NG17 view transitions, design systems, Tailwind, and Stylelint. Produces a provenance-tagged, severity-ranked report before changing anything; fixes on approval in verified batches and never commits.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .junie/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- angular-developerSkill
- brainstormingSkill
- code-reviewSkill
- create-a-skillSkill
- create-e2e-testsSkill
- diagnosing-bugsSkill
- frontend-designSkill
- git-stack-rewriteSkill
- grill-meSkill
- grill-with-styleSkill
- handoverSkill
- implement-planSkill
- ng-accessibilitySkill
- ng-data-accessSkill
- ng-formsSkill
- ng-migrateSkill
- ng-performanceSkill
- ng-prototypeSkill
- ng-refactorSkill
- ng-review-architectureSkill
- ng-review-style-guideSkill
- ng-securitySkill
- ng-signal-storeSkill
- ng-testingSkill
- ng-verify-featureSkill
- spartanSkill
- test-driven-developmentSkill
- unslopSkill
- update-skills-directorySkill
- update-skillsSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 98
Default scope is the whole project.
- Very specific: line 101
every *.scss (component styles, src/styles.scss, src/styles/ partials),
- Very specific: line 115
Write a grouped markdown report to styling-audit.md at the project root (path overridable), and render the same grouped summary in chat.
- Distinctive: line 122
Only after you say go. Apply in small batches, each batch one coherent kind of change:
- Distinctive: line 131
Verify and checkpoint after every batch (see the gauntlet).
- Distinctive: line 135
Run the gauntlet on each batch and read the diff top-to-bottom.
- Distinctive: line 142
After every fix batch, run in order and don't proceed until green:
- Distinctive: line 163
Preserve meaning: Keep meaningful comments and documented hacks/workarounds (the guide asks you to _document_ complex CSS, not delete it).
- Distinctive: line 166
Advisory ≠ violation: Never auto-apply advisory items.
- Distinctive: line 167
Git discipline: Start from a clean working tree.
- Distinctive: line 215
Use the repository VERIFICATION.md when present.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
| Tag | Source |
[repo] | This project's written style guide – style-guide.scss.md, the styling rules in style-guide.html.md, and the styling-relevant TS rules in style-guide.ts.md |
[deck] | The workshop deck "Angular Styling" (the topics, framing, and "Best Practices/Tips" recap) |
[angular.dev] | The official Angular coding style guide and the Styling components / view transitions guides |
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.
| # | Category | Gist | Sources |
| 1 | Template bindings | [class.x] / [style.x] over ngClass / ngStyle; inline styles only when computed/dynamic | [repo] [deck] [angular.dev] |
| 2 | View Encapsulation | Emulated is the default; None demands a project prefix; ShadowDom trade-offs | [repo] [deck] [angular.dev] |
| 3 | SCSS architecture & files | Component-scoped vs global split; @use / @forward not @import; partials & layer order; co-located, same-name, kebab-case style files | [repo] [deck] [angular.dev] |
| 4 | Design tokens | Global CSS custom properties for tokens; :host for component knobs; no raw colors in components | [repo] [deck] |
| 5 | Selectors & nesting | Classes/elements not ids; BEM with the project prefix; ≤ 2 (rarely 3) nesting; no & nesting | [repo] |
| 6 | Forbidden constructs | No !important, ::ng-deep, float, inline styles, or reused library classes | [repo] [deck] |
| 7 | Units & values | rem for type; unitless 0; leading 0; shorthand/intrinsic; logical properties; :has() | [repo] |
| 8 | Framework-class leakage | Don't bind installed frameworks' classes directly (ag-grid .ag-*, ng-select .ng-*, spartan; Material/PrimeNG as a generic aside); prefix; customize via each framework's theming vars | [repo] [deck] |
Advisory – opportunities, not violations. Reported separately; never auto-applied. Detail in references/component-frameworks.md.
inject(DOCUMENT)for SSR-safedocumentaccess (scroll, body class). The write side (sanitization, raw DOM) defers tong-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 insrc/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@layerorder 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, andViewEncapsulation.Nonefor a design-system library ([angular.dev]); and consider adding Stylelint to make the mechanical rules deterministically enforceable.[deck]
Severity (mirrors the style guide)
| Severity | Means | Maps to |
| 🔴 Must | A violation – fix it | the guide's "Must do" / "Don't" |
| 🟡 Should | A strong recommendation – fix unless justified | the guide's "Should do" |
| 🔵 Advisory | An opportunity to consider | the deck's adoption topics & "consider Stylelint" |
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)andencapsulationin@Componentdecorators, - 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, unitless0, leading0, 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 migratesngClass/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– theanyComponentStylebudget, critical CSS, framework-CSS weight.ng-security– inline styles as a CSP concern; the write side ofdocumentaccess.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/@forwardmigration, design tokens vs:hostknobs, 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, theinject(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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

