# component-builder

Adopt this skill: https://proskills.md/skills/other/kostja94-bricks-skills-component-builder

Page: https://proskills.md/skills/other/kostja94-bricks-skills-component-builder
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/component-builder/SKILL.md
size: 3859
upstream: https://github.com/kostja94/bricks/blob/main/skills/component-builder/SKILL.md

```text
---
name: component-builder
description: Build new interface components and bounded composition patterns inside an existing project. Use for named components, interface blocks, and workspaces. Preserve the target project's design system and stack; for a complete new page with page-level structure and multiple sections, use Pagina page-builder instead. Do not use to audit or reconstruct an existing component, plan a whole product or website, or handle purely editorial copy requests.
metadata:
  version: 0.2.0
---

# Component Builder

Create new components that belong in the target product instead of producing isolated demo UI.

## Start With The Project

Inspect the relevant page, nearby components, design tokens, dependencies, content model, responsive conventions, and tests before choosing an implementation. Reuse established primitives and icon libraries. Do not replace an existing design system merely because another library is familiar.

Identify:

- the requested component concept and user task;
- the surface and interface type;
- where the new component belongs and which existing primitives it may reuse;
- the component's real content and states;
- the target stack and existing ownership boundary.

For a page composition, define the page's job and reuse child components from the catalog. Do not turn a page pattern into a second maintenance source for every component it contains.

## Load Only Relevant Guidance

Read [references/workflow.md](references/workflow.md) for construction work. Read [references/foundational-controls.md](references/foundational-controls.md) when the request involves Button, Link, Input, Select, Form, or another foundational control and [references/quality-gates.md](references/quality-gates.md) before final verification.

Read [references/pagina.md](references/pagina.md) when the request may be a complete page rather than a bounded component.

Find the component ID in [../../catalog/components.json](../../catalog/components.json), then read only its referenced component file. If the requested concept is absent, use the shared workflow, state the inferred canonical name in the result, and do not invent a permanent catalog entry unless the task includes repository maintenance.

## Build

1. Define the semantic responsibility and boundary before styling.
2. Choose a variant from context and content, not fashion.
3. Preserve project conventions and integrate real content or data contracts.
4. Implement expected states, responsive behavior, keyboard behavior, and failure handling.
5. Verify the component in its actual page context. A component that only looks correct in isolation is incomplete.

## Boundaries

- One component concept has one maintained reference. Role, placement, visual variant, and runtime state do not create new catalog entries.
- Established independent terminology and discovery intent may justify separate entries that share a model, as with Grid, List, and Masonry.
- A component reference is guidance, not a fixed code template.
- Bounded composition patterns may coordinate catalog components. Complete page construction belongs to Pagina; whole-site information architecture and product planning remain outside both component construction and this skill.
- Stop and report the scope mismatch when the named component already exists and the request is primarily an audit, optimization, or reconstruction.
- Do not add dependencies without a concrete implementation benefit.
- Do not claim compliance, performance, or conversion outcomes that were not tested.
- Use proven domain libraries when the component depends on complex editors, tables, charts, calendars, accessibility primitives, or agent runtimes.

## Completion

Report what changed, which project conventions were reused, how the component was verified, and any material constraint that remains.
```

## File: README.md
upstream: https://github.com/kostja94/bricks/blob/main/README.md

````text
# Bricks: Component Layer for AI Agents

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/kostja94/bricks)](https://github.com/kostja94/bricks/stargazers)
[![Last commit](https://img.shields.io/github/last-commit/kostja94/bricks)](https://github.com/kostja94/bricks/commits/main)

Bricks gives coding agents implementation-aware contracts for building and maintaining interface components that belong in an existing product, codebase, and design system.

It helps an agent understand a component's responsibility, context, variants, content, interaction states, technical boundary, and verification requirements before writing code.

## Install

```bash
npx skills add kostja94/bricks --skill component-builder
```

Give the agent a bounded component task and the context needed to integrate it:

```text
Use component-builder to build the footer for this bilingual SaaS site.

Read the existing routes, components, design tokens, framework, and responsive conventions first. Reuse project primitives, include the real product, resource, company, and legal destinations, and verify keyboard access on mobile and desktop.
```

See the complete [Footer request example](examples/footer-request.md).

## Component Governance

Choose the entry point by the requested outcome:

| Skill | Outcome |
|---|---|
| `component-builder` | Build a missing component in its real page context |
| `component-inventory` | Discover actual pages, components and inline UI; save or refresh the project component system document |
| `component-auditor` | Analyze semantic duplicates and drift, align one family at a time, or implement confirmed reconstruction |
| `component-cleanup` | Remove verified unused components, abandoned generated UI and migration leftovers with their exclusive support files |

Install a governance entry point with `npx skills add kostja94/bricks --skill component-inventory` (substitute the required skill name).

Inventory produces a required project-owned document covering both page-to-component and component-to-page relationships, real content sources, conditional branches, project contracts, decisions, progress and verification gaps. Reuse its existing location; otherwise use `docs/component-system.md`. Large inventories may use linked generated appendices. Keep product content in its original owner.

The maintenance loop is discovery → saved component system document → semantic decisions → authorized construction or migration → verified cleanup → refreshed document. Each skill also supports bounded tasks without requiring every other skill to be installed. An unimported component is a cleanup candidate, not automatic proof of disuse: dynamic entries, public exports and retained base libraries must be checked.

For example:

```text
Use component-inventory to map every page and component in this repository.
Save the relationships and coverage gaps in our existing component system document.
Then use component-auditor in audit-only mode to propose consolidation by semantic family.
```

## Why Bricks Exists

Agents are already capable of writing component code. The harder problem is deciding what the component is responsible for and making it fit the product around it.

A generated Footer may invent routes. A FAQ may hide answers from assistive technology. A Task Input may omit loading, cancellation, invalid input, or result recovery. An Agent Workspace may look convincing in a demo while having no workable boundary between conversation, tools, artifacts, and user control.

Bricks addresses that reasoning layer. It guides the agent toward a project-native implementation instead of shipping an isolated demo or importing a second design system by habit.

## What Bricks Is

| Bricks provides | Bricks does not provide |
|-----------------|-------------------------|
| One maintained contract per component concept | A separate Skill for every visual style |
| Semantic responsibility and ownership boundaries | A fixed React, Vue, or CSS component package |
| Context-aware variants and expected states | A universal design system |
| Integration and verification guidance | A gallery of interchangeable mockups |
| Stable component IDs for Agent tooling | Permission to replace project conventions |

One component can have many valid designs. Bricks keeps Footer guidance in one reference and lets the target product determine its layout, typography, density, content, and implementation.

## Component Coverage

The catalog spans small primitives, content structures, conversion elements, and composed Agent interfaces:

| Group | Representative components |
|-------|---------------------------|
| Navigation and orientation | Navigation Menu, Footer, Breadcrumb, Sidebar, Table of Contents |
| Content and explanation | Article Content Layout, Author Bio, FAQ Section, How-to Section, Tabs, Accordion |
| Conversion and trust | CTA, Newsletter Signup, Comparison Table, Testimonials, Trust Signals |
| Layout and presentation | Card, Grid, List, Masonry, Carousel, Modal, Announcement Banner |
| Agent and tool interfaces | Task Input, Conversation, Chat Panel, Agent Workspace, CMS Editor Workspace |

Browse the machine-readable inventory in [`catalog/components.json`](catalog/components.json). Component IDs remain stable while their references can grow as new contexts and constraints are learned.

## From Request to Integrated Component

The `component-builder` does not begin with a preferred library or visual treatment.

1. It inspects the page, nearby components, tokens, dependencies, data model, responsive conventions, and tests.
2. It identifies the canonical component concept, user task, surface, and ownership boundary.
3. It loads only the matching component reference and shared quality gates.
4. It selects a variant from real content and context.
5. It reuses the project's primitives and implements required states and interactions.
6. It verifies the component inside its actual page, not only in an isolated preview.

For components with complex domain behavior, such as editors, data grids, charts, calendars, or accessibility primitives, the agent should use a proven library when the project does not already provide one.

## Context Matters

The same component identity changes meaning across surfaces and pages.

- A public marketing Footer organizes product, resource, company, and legal destinations.
- An authenticated application Footer may be absent or reduced to operational links.
- A documentation Sidebar needs hierarchy, active state, deep navigation, and narrow-screen behavior.
- A dashboard Sidebar must also account for permissions, workspaces, collapsed states, and task frequency.

Bricks records these contextual decisions without turning every combination into a new component name.

## Working With Pagina

[Pagina](https://github.com/kostja94/pagina) and Bricks operate at different levels:

```text
Pagina defines the complete page contract
                    |
                    v
Pagina recommends required component concepts
                    |
                    v
Bricks guides project-native component construction
                    |
                    v
The target repository owns the final code and design system
```

Use Pagina when the task is a complete page with page-level content, sections, routes, and multiple components. Use Bricks when the task is one named component, a bounded composition pattern, or existing-component governance. Generic page recommendations stay in Pagina; actual project consumer maps stay in the target project. Pagina remains usable without Bricks when the target project already has every component it needs.

## Boundaries

Bricks builds new interface components and bounded composition patterns, and maintains existing components through inventory, audit and cleanup. It does not plan a whole product, define a complete website, or own purely editorial copy.

Com
````
