josepfernande/halo-ui/lib-ui-architecture

Claude Code and agent skill by josepfernande/halo-ui

Trust tier 3
  • community
Source check pending

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-architecture

SKILL.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)

  1. Tokens first. No hardcoded colors, spacing, or radius. Every value comes

from a token.

  1. Standalone only. No NgModules. Every component, directive, and pipe is

standalone: true.

  1. Signals first. Use Signals, not RxJS, for local state, UI state, and

internal interactions. Reserve RxJS for streams, async events, and interop.

  1. CSS variables first. Prefer native CSS and custom properties. Reject

heavy SCSS, mixin stacks, and utility-class frameworks.

  1. CDK over custom. Use Angular CDK for overlays, a11y, focus, keyboard, and

scrolling. Do not reimplement.

  1. 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:

  1. Foundation — raw values: --primary-600, --neutral-500, --radius-lg,

--spacing-md.

  1. 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-*.

  1. 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

SituationRule
Adding a color, spacing, or radius valueUse semantic or component token. Reject hardcoded values.
Component receives a color inputType as string (theme-registered). Reject closed enums.
Component needs overlay, a11y, focus, keyboard, or scrollingUse Angular CDK primitives. Reject custom implementations.
Component local or UI stateUse Signals. Reject BehaviorSubject for UI state.
Cross-component stylingUse component tokens. Reject global utility classes and shared mutable state.
Component file sizeStay within 300–400 lines. Split otherwise.
Third-party dependencyJustify it. Default to no — avoid lodash, utility libraries, heavy CSS frameworks.

Execution Steps

  1. Confirm the change targets the halo-ui repo. 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.

  1. Re-read the Wiki source of truth if any rule application is ambiguous. Do not

invent.

  1. Apply the hard rules to your output: spec criteria, design decisions, task

acceptance, code, and verification checklist must reference these rules explicitly.

  1. 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).

  1. 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/josepfernande/halo-ui/lib-ui-architecture/badge)](https://verified-skill.com/skills/josepfernande/halo-ui/lib-ui-architecture)

Something wrong with this skill or its page? Tell us.