josepfernande/halo-ui/lib-ui-architecture
Claude Code and agent skill by josepfernande/halo-ui
- community
Checking that the SKILL.md file is still in the repository.
Trigger: halo-ui, Angular UI library, ha- components, design tokens, theming, sdd design spec tasks apply verify. Apply the six hard rules and three-layer token system to every halo-ui artifact.
Install
npx vskill@latest install josepfernande/halo-ui/lib-ui-architectureSKILL.md
The same SKILL.md was published earlier as josepfernande/halo-ui/lib-ui-architecture.
Activation Contract
Load this skill whenever work targets the halo-ui repository: any implementation, refactor, or review of Angular components, theming, or tokens. This applies unconditionally, regardless of whether the collaborator uses the SDD workflow — the architecture rules below are a project constraint, not a byproduct of any particular process.
SDD is optional per collaborator. If a contributor runs an sdd-* phase (explore, propose, spec, design, tasks, apply, verify), this skill also governs that phase's output — the phase structure doesn't replace the rules, it's just one way of organizing work that happens to also be bound by them. A contributor who never touches sdd-* is bound by the same rules just the same, applied directly to their implementation, refactor, or review.
The skill is the operational contract for the architecture documented in the GitHub Wiki. It does not replace reading the source Wiki page when a decision is non-obvious.
Hard Rules (non-negotiable)
- Tokens first. No hardcoded colors, spacing, or radius. Every value comes
from a token.
- Standalone only. No NgModules. Every component, directive, and pipe is
standalone: true.
- Signals first. Use Signals, not RxJS, for local state, UI state, and
internal interactions. Reserve RxJS for streams, async events, and interop.
- CSS variables first. Prefer native CSS and custom properties. Reject
heavy SCSS, mixin stacks, and utility-class frameworks.
- CDK over custom. Use Angular CDK for overlays, a11y, focus, keyboard, and
scrolling. Do not reimplement.
- Consistent APIs. Naming, inputs, outputs, and variants follow project
conventions: ha- prefix, size=sm|md|lg, variant=solid|outline|ghost, color as a string (theme-registered, never a closed enum).
Token System
Three layers, in order of definition:
- Foundation — raw values:
--primary-600,--neutral-500,--radius-lg,
--spacing-md.
- Semantic —
--ha-primary(and any other consumer-registered color name;
only primary ships by default), plus the non-color passthrough --ha-spacing-*, --ha-radius-*, --ha-gap-*, --ha-icon-size-*, --ha-font-size-*.
- Component —
--ha-button-bg,--ha-button-color,
--ha-input-focus-ring.
Scale naming (spacing, radius, font-size, size) is semantic (sm/md/lg), never numeric (-1, -2, -4). This matches the suffix convention already shipped in component tokens (button.tokens.ts, input-text.tokens.ts) — do not introduce a numeric-indexed scale anywhere in the token system.
Components consume ONLY semantic and component tokens. Foundation tokens are off-limits inside components. The Theme Engine (provideHaTheme()) auto-derives hover, active, and contrast variants from user-registered colors.
Decision Gates
| Situation | Rule | |
|---|---|---|
| Adding a color, spacing, or radius value | Use semantic or component token. Reject hardcoded values. | |
| Component receives a color input | Type as string (theme-registered). Reject closed enums. | |
| Component needs overlay, a11y, focus, keyboard, or scrolling | Use Angular CDK primitives. Reject custom implementations. | |
| Component local or UI state | Use Signals. Reject BehaviorSubject for UI state. | |
| Cross-component styling | Use component tokens. Reject global utility classes and shared mutable state. | |
| Component file size | Stay within 300–400 lines. Split otherwise. | |
| Third-party dependency | Justify it. Default to no — avoid lodash, utility libraries, heavy CSS frameworks. |
Execution Steps
- Confirm the change targets the
halo-uirepo. If the collaborator is running
an SDD phase, identify which artifact you own for that phase (spec, design, task, implementation, verification). If not, apply the rules directly to the implementation, refactor, or review at hand — no phase breakdown required.
- Re-read the Wiki source of truth if any rule application is ambiguous. Do not
invent.
- Apply the hard rules to your output: spec criteria, design decisions, task
acceptance, code, and verification checklist must reference these rules explicitly.
- For each component, place files at
libs/<lib>/src/lib/<comp>.{component.ts,component.html,component.css,types.ts,tokens.ts,constants.ts,utils.ts} with index.ts at the entry-point root (Nx convention; there is no public-api.ts).
- Verification phase: produce a checklist mapping each of the six hard rules to
the evidence (file, line, test) that proves compliance. Flag any deviation as a blocker, not a warning.
Output Contract
Every phase or direct implementation must return:
- Rule compliance map: for each of the 6 hard rules, the artifact(s) that
satisfy it.
- Token map: which semantic and component tokens the change introduces or
consumes.
- CDK usage: which CDK module(s) the change relies on (if any).
- Limits: confirm the change respects the 300–400 line component cap.
- Deviations: any rule the change cannot satisfy, with rationale and
proposed follow-up.
References
- Architecture & Foundation:
../../docs/architecture-and-foundation.md - Repo:
https://github.com/JosepFernande/halo-ui
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/lib-ui-architecture/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/josepfernande/halo-ui/lib-ui-architecture)