@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/claude-code/harness-design-web/SKILL.md

@@ -0,0 +1,360 @@
+# Harness Design Web
+
+> Token-bound web component generation. Scaffold from design tokens and aesthetic intent, implement with Tailwind/CSS and React/Vue/Svelte patterns, and verify every value references the token set — no hardcoded colors, fonts, or spacing.
+
+## When to Use
+
+- Generating new web components that must conform to the project's design system tokens
+- When `on_new_feature` triggers fire with web UI scope requiring token-bound component generation
+- When `on_commit` triggers fire and new components contain hardcoded design values that should reference tokens
+- Implementing design intent from `design-system/DESIGN.md` into concrete Tailwind classes, CSS custom properties, or CSS-in-JS theme values
+- Converting mockups or wireframes into token-bound component code for React, Vue, or Svelte
+- NOT for generating design tokens themselves (use harness-design-system)
+- NOT for establishing aesthetic direction or anti-patterns (use harness-design)
+- NOT for accessibility auditing (use harness-accessibility)
+- NOT for mobile platform components (use harness-design-mobile)
+
+## Process
+
+### Phase 1: SCAFFOLD — Read Tokens, Detect Framework, Plan Structure
+
+1. **Read design tokens.** Load `design-system/tokens.json` (W3C DTCG format). Extract:
+   - Color tokens: primary, secondary, accent, neutral ramps, semantic colors (success, warning, error, info)
+   - Typography tokens: heading and body font families, font weights, font sizes, line heights
+   - Spacing tokens: spacing scale values (xs through 2xl or equivalent)
+   - If `design-system/tokens.json` does not exist, stop and instruct the user to run `harness-design-system` first.
+
+2. **Read design intent.** Load `design-system/DESIGN.md` for:
+   - Aesthetic direction (style, tone, differentiator) from harness-design output
+   - Anti-patterns to avoid (e.g., "no gradients on data elements," "no decorative borders")
+   - Platform-specific web notes (CSS strategy preferences, animation guidelines, responsive behavior)
+   - If `design-system/DESIGN.md` does not exist, warn the user and proceed with tokens only. Recommend running `harness-design` for richer output.
+
+3. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` — enforcement level (`strict`, `standard`, `permissive`). Default to `standard`.
+   - `design.platforms` — confirm `web` is in the platforms list.
+   - `design.tokenPath` — custom token path (default: `design-system/tokens.json`).
+
+4. **Detect web framework.** Scan the project for:
+   - **React:** `package.json` contains `react` or `next` dependency, `.tsx`/`.jsx` files exist
+   - **Vue:** `package.json` contains `vue` or `nuxt` dependency, `.vue` files exist
+   - **Svelte:** `package.json` contains `svelte` or `@sveltejs/kit`, `.svelte` files exist
+   - **Vanilla:** No framework detected, output plain HTML/CSS
+   - If the user specified `--framework`, use that override.
+
+5. **Detect CSS strategy.** Scan for:
+   - **Tailwind:** `tailwind.config.*` exists, `@tailwind` directives in CSS, `class=` with Tailwind utility patterns
+   - **CSS Modules:** `.module.css` or `.module.scss` files exist
+   - **CSS-in-JS:** `styled-components`, `@emotion/styled`, `stitches` imports detected
+   - **Vanilla CSS:** Global `.css`/`.scss` files with no module or utility pattern
+   - If the user specified `--cssStrategy`, use that override.
+
+6. **Load platform-specific web rules.** Read `agents/skills/shared/design-knowledge/platform-rules/web.yaml` for web-specific design rules including responsive breakpoints, browser compatibility considerations, and CSS best practices.
+
+7. **Load anti-pattern definitions.** Read anti-pattern files from `agents/skills/shared/design-knowledge/anti-patterns/`:
+   - `typography.yaml` — typographic anti-patterns (too many fonts, inconsistent scales)
+   - `color.yaml` — color anti-patterns (hardcoded hex, insufficient contrast)
+   - `layout.yaml` — layout anti-patterns (magic numbers, inconsistent spacing)
+   - `motion.yaml` — motion anti-patterns (excessive animation, missing reduced-motion)
+
+8. **Build token-to-CSS mapping.** Create a lookup table that maps each token to its CSS representation based on the detected strategy:
+   - **Tailwind:** `color.primary.500` maps to `text-primary-500` / `bg-primary-500` (requires `tailwind.config` theme extension)
+   - **CSS custom properties:** `color.primary.500` maps to `var(--color-primary-500)`
+   - **CSS-in-JS:** `color.primary.500` maps to `theme.color.primary[500]`
+
+9. **Plan component structure.** For the requested component(s), define:
+   - Component file path(s) following project conventions
+   - Props interface / type definition
+   - Which tokens will be consumed (colors, typography, spacing)
+   - Responsive behavior (breakpoints, layout changes)
+   - Present the scaffold plan to the user before proceeding.
+
+### Phase 2: IMPLEMENT — Generate Token-Bound Components
+
+1. **Generate framework-specific component code.** Based on detected framework:
+
+   **React (TSX):**
+   - Functional component with TypeScript props interface
+   - All color values reference tokens (via Tailwind classes, CSS variables, or theme object)
+   - All typography values reference tokens (font family, weight, size from token set)
+   - All spacing values reference tokens (padding, margin, gap from spacing scale)
+   - Export component with display name
+
+   **Vue (SFC):**
+   - Single File Component with `<script setup lang="ts">`
+   - Props defined with `defineProps` and TypeScript interface
+   - Scoped styles reference CSS custom properties mapped from tokens
+   - Template uses token-derived classes or inline styles via CSS variables
+
+   **Svelte:**
+   - Component with TypeScript `<script lang="ts">`
+   - Props exported with `export let` declarations
+   - Styles reference CSS custom properties mapped from tokens
+   - Reactive declarations for computed style values
+
+   **Vanilla HTML/CSS:**
+   - Semantic HTML structure
+   - CSS custom properties for all design values
+   - No inline styles with hardcoded values
+
+2. **Generate CSS strategy artifacts.** Based on detected CSS strategy:
+
+   **Tailwind:**
+   - Extend `tailwind.config` theme with token values (if not already present)
+   - Map tokens to Tailwind utility classes in components
+   - Use `@apply` sparingly — prefer utility classes in markup
+   - Generate token-to-Tailwind mapping comment block at top of component
+
+   **CSS Custom Properties:**
+   - Generate `:root` declarations for all consumed tokens
+   - Components reference `var(--token-name)` exclusively
+   - No hardcoded hex, rgb, hsl, or font values in component styles
+
+   **CSS-in-JS:**
+   - Generate theme object from tokens
+   - Components consume theme via provider/hook pattern
+   - All style values reference theme properties
+
+3. **Apply design intent constraints.** For each generated component:
+   - Check against anti-patterns from `design-system/DESIGN.md` and `agents/skills/shared/design-knowledge/anti-patterns/`
+   - Enforce style guidelines (e.g., minimal style means no decorative effects)
+   - Apply tone-appropriate color usage (e.g., cool tone means no warm accents in neutral UI)
+   - Respect platform-specific web notes (animation preferences, responsive behavior)
+
+4. **Add USES_TOKEN annotations.** Insert comments in generated code documenting which tokens are consumed:
+   ```
+   /* @design-token color.primary.500 — primary action background */
+   /* @design-token typography.heading.fontFamily — section heading */
+   /* @design-token spacing.md — card internal padding */
+   ```
+   These annotations enable the knowledge graph to create `USES_TOKEN` edges from this component to the consumed `DesignToken` nodes.
+
+### Phase 3: VERIFY — Check Token Binding and Design Constraints
+
+1. **Scan for hardcoded values.** Use Grep to search generated files for:
+   - Hardcoded color values: hex (`#[0-9a-fA-F]{3,8}`), `rgb()`, `hsl()`, named colors
+   - Hardcoded font families: `font-family:` declarations not referencing tokens
+   - Hardcoded spacing: pixel/rem values in margin/padding/gap not from the token scale
+   - Each finding is a violation: the component uses a value not bound to a token.
+
+2. **Verify token coverage.** For every design value in the generated component:
+   - Confirm it resolves to a token in `design-system/tokens.json`
+   - Confirm the token path is valid (e.g., `color.primary.500` exists in the token tree)
+   - Report orphan references (token annotations pointing to non-existent tokens)
+
+3. **Check anti-pattern compliance.** Cross-reference generated code against anti-patterns declared in `design-system/DESIGN.md` and the anti-pattern definitions in `agents/skills/shared/design-knowledge/anti-patterns/`:
+   - Grep for patterns matching each declared anti-pattern
+   - Flag violations with file path, line number, and the specific anti-pattern violated
+
+4. **Query the knowledge graph.** If a graph exists at `.harness/graph/`:
+   - Use `DesignIngestor` to verify `DesignToken` nodes exist for all referenced tokens
+   - Verify `PLATFORM_BINDING` edges exist for web platform tokens
+   - Use `DesignConstraintAdapter` to check for `VIOLATES_DESIGN` edges
+   - Report any constraint violations with severity based on `design.strictness`
+
+5. **Assign severity based on `designStrictness`:**
+   - `permissive` — all findings are `info`
+   - `standard` — hardcoded values and anti-pattern violations are `warn`, accessibility violations are `error`
+   - `strict` — hardcoded values are `error` (blocks), anti-pattern violations are `warn`, accessibility violations are `error`
+
+6. **Report verification results.** Present:
+
+   ```
+   WEB-001 [warn] Hardcoded color #3b82f6 — should reference token "color.primary.500"
+     File: src/components/Button.tsx:12
+     Fix: Replace with Tailwind class "bg-primary-500" or var(--color-primary-500)
+
+   WEB-002 [info] Anti-pattern: gradient on card background
+     File: src/components/MetricCard.tsx:28
+     Fix: Use solid background from token "color.neutral.50"
+   ```
+
+7. **Run `harness validate`.** After verification, run project-level validation to confirm the new components integrate cleanly.
+
+## Harness Integration
+
+- **`harness validate`** — Run after generating components to verify project health. New files must not break existing constraints.
+- **`harness scan`** — Run after component generation to update the knowledge graph with new `USES_TOKEN` edges from generated components to consumed tokens.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) — Verifies that `DesignToken` nodes exist for all tokens referenced by generated components. If tokens are missing from the graph, run `harness scan` to re-ingest.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) — Checks for `VIOLATES_DESIGN` edges during the VERIFY phase. Reports constraint violations at the configured strictness level.
+- **`harness-design-system`** — Dependency. This skill reads tokens generated by harness-design-system. If tokens do not exist, instruct the user to run harness-design-system first.
+- **`harness-design`** — Dependency. This skill reads aesthetic intent from harness-design output (`design-system/DESIGN.md`). Anti-pattern enforcement and style constraints come from the design intent document.
+- **`harness-impact-analysis`** — When tokens change, impact analysis traces which components consume affected tokens via `USES_TOKEN` edges. Use this to identify components that need regeneration after token updates.
+
+**Graph naming convention:** This skill uses PascalCase for node types (`DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`USES_TOKEN`, `PLATFORM_BINDING`, `VIOLATES_DESIGN`) as conceptual labels. The graph schema registers these as snake_case identifiers (`design_token`, `design_constraint`, `uses_token`, `platform_binding`, `violates_design`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
+
+## Success Criteria
+
+- Generated components reference design tokens exclusively — no hardcoded color, font, or spacing values
+- Framework detection correctly identifies React, Vue, Svelte, or vanilla projects
+- CSS strategy detection correctly identifies Tailwind, CSS Modules, CSS-in-JS, or vanilla CSS
+- Token-to-CSS mapping produces correct output for each CSS strategy (Tailwind classes, CSS custom properties, theme object references)
+- `@design-token` annotations are present for every consumed token
+- Anti-pattern compliance check catches violations declared in `design-system/DESIGN.md`
+- Verification report uses severity levels matching `design.strictness` configuration
+- `harness validate` passes after component generation
+
+## Examples
+
+### Example: React + Tailwind Button Component
+
+**Context:** SaaS dashboard project. React with Tailwind CSS. Tokens generated by harness-design-system. Design intent established by harness-design (minimal style, cool professional tone).
+
+**SCAFFOLD output:**
+
+```
+Framework detected:   React (Next.js)
+CSS strategy:         Tailwind CSS (tailwind.config.ts)
+Tokens loaded:        42 tokens from design-system/tokens.json
+Design intent:        Minimal, cool professional (from DESIGN.md)
+Component plan:       Button with primary/secondary/ghost variants
+Token consumption:    color.primary.*, color.neutral.*, typography.body, spacing.sm/md
+```
+
+**IMPLEMENT output (Button.tsx):**
+
+```tsx
+/* @design-token color.primary.500 — primary variant background */
+/* @design-token color.primary.700 — primary variant hover */
+/* @design-token color.neutral.50 — ghost variant background */
+/* @design-token color.neutral.900 — ghost variant text */
+/* @design-token typography.body.fontFamily — button label */
+/* @design-token typography.body.fontWeight — button label weight */
+/* @design-token spacing.sm — button horizontal padding */
+/* @design-token spacing.xs — button vertical padding */
+
+import type { ButtonHTMLAttributes } from 'react';
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  className = '',
+  children,
+  ...props
+}: ButtonProps) {
+  const baseClasses =
+    'inline-flex items-center justify-center font-body font-medium rounded-md transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500';
+
+  const variantClasses = {
+    primary: 'bg-primary-500 text-white hover:bg-primary-700',
+    secondary: 'border border-primary-500 text-primary-700 hover:bg-primary-50',
+    ghost: 'text-neutral-900 hover:bg-neutral-100',
+  };
+
+  const sizeClasses = {
+    sm: 'px-spacing-sm py-spacing-xs text-sm',
+    md: 'px-spacing-md py-spacing-sm text-base',
+    lg: 'px-spacing-lg py-spacing-md text-lg',
+  };
+
+  return (
+    <button
+      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${className}`}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+**VERIFY output:**
+
+```
+Verification Results
+--------------------
+Hardcoded values:    PASS (0 hardcoded colors, fonts, or spacing)
+Token coverage:      PASS (8/8 referenced tokens exist in tokens.json)
+Anti-pattern check:  PASS (no gradients, no decorative borders)
+Design constraints:  PASS (no VIOLATES_DESIGN edges)
+Harness validate:    PASS
+```
+
+### Example: Vue + CSS Custom Properties Card Component
+
+**Context:** E-commerce project. Vue 3 with CSS custom properties. Tokens from harness-design-system.
+
+**IMPLEMENT output (ProductCard.vue):**
+
+```vue
+<!-- @design-token color.neutral.50 — card background -->
+<!-- @design-token color.neutral.200 — card border -->
+<!-- @design-token color.neutral.900 — card text -->
+<!-- @design-token typography.heading.fontFamily — product title -->
+<!-- @design-token typography.body.fontFamily — product description -->
+<!-- @design-token spacing.md — card padding -->
+<!-- @design-token spacing.sm — content gap -->
+
+<script setup lang="ts">
+interface Props {
+  title: string;
+  description: string;
+  price: string;
+  imageUrl: string;
+  imageAlt: string;
+}
+
+defineProps<Props>();
+</script>
+
+<template>
+  <article class="product-card">
+    <img :src="imageUrl" :alt="imageAlt" class="product-card__image" />
+    <div class="product-card__content">
+      <h3 class="product-card__title">{{ title }}</h3>
+      <p class="product-card__description">{{ description }}</p>
+      <span class="product-card__price">{{ price }}</span>
+    </div>
+  </article>
+</template>
+
+<style scoped>
+.product-card {
+  background: var(--color-neutral-50);
+  border: 1px solid var(--color-neutral-200);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+
+.product-card__content {
+  padding: var(--spacing-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-sm);
+}
+
+.product-card__title {
+  font-family: var(--typography-heading-fontFamily);
+  font-weight: var(--typography-heading-fontWeight);
+  color: var(--color-neutral-900);
+}
+
+.product-card__description {
+  font-family: var(--typography-body-fontFamily);
+  color: var(--color-neutral-700);
+}
+</style>
+```
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No component generation without reading tokens from harness-design-system.** The SCAFFOLD phase requires `design-system/tokens.json` to exist. If tokens have not been generated, instruct the user to run harness-design-system first. Do not generate components with hardcoded values as a fallback.
+- **No hardcoded design values in generated output.** Every color, font, and spacing value must reference a token. If a needed token does not exist, instruct the user to add it via harness-design-system rather than hardcoding the value.
+- **No framework-specific code without framework detection.** The SCAFFOLD phase must detect or receive the target framework before generating components. Do not guess or default to React.
+- **No generation without scaffold plan confirmation.** The SCAFFOLD phase must present a component plan to the user. Do not generate code without the user confirming the structure and token consumption plan.
+- **No graph mutations without validating node types.** When creating `USES_TOKEN` or `PLATFORM_BINDING` edges, verify the node and edge types are registered in the graph schema before writing.
+
+## Escalation
+
+- **When `design-system/tokens.json` does not exist:** Instruct the user: "Design tokens have not been generated. Run `harness-design-system` first to create `design-system/tokens.json`, then re-run `harness-design-web` for token-bound component generation."
+- **When the project uses an undetected framework:** Ask the user to specify via the `--framework` CLI argument. Log: "Could not auto-detect web framework. Please specify: `harness skill run harness-design-web --framework react|vue|svelte|vanilla`."
+- **When tokens are insufficient for the requested component:** Report which tokens are missing: "Component requires a `color.accent.500` token but it does not exist in `tokens.json`. Run `harness-design-system` to add the missing token, or choose an existing alternative." Do not hardcode a fallback.
+- **When anti-patterns conflict with the requested design:** Present the conflict: "The requested gradient background violates the 'no gradients on data elements' anti-pattern from DESIGN.md. Options: (1) Remove the gradient and use a solid token color, (2) Update the anti-pattern list via `harness-design` if the intent has changed."
+- **When the knowledge graph is unavailable:** Skip graph operations in SCAFFOLD and VERIFY phases. Log: "Graph not available at `.harness/graph/` — skipping token node verification and USES_TOKEN edge creation. Run `harness scan` later to populate." Continue with file-based operations.

package/dist/agents/skills/claude-code/harness-design-web/skill.yaml

@@ -0,0 +1,52 @@
+name: harness-design-web
+version: "1.0.0"
+description: Token-bound web component generation with Tailwind/CSS, React/Vue/Svelte patterns, and design constraint verification
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_new_feature
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-design-web
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: framework
+      description: Target framework (react, vue, svelte, vanilla)
+      required: false
+    - name: cssStrategy
+      description: CSS strategy (tailwind, css-modules, css-in-js, vanilla)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-design-web
+    path: string
+type: rigid
+phases:
+  - name: scaffold
+    description: Read tokens and design intent, detect framework and CSS strategy, plan component structure
+    required: true
+  - name: implement
+    description: Generate token-bound components with framework-specific patterns
+    required: true
+  - name: verify
+    description: Verify all values reference tokens, no hardcoded colors/fonts/spacing, run design constraints
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-design-system
+  - harness-design