Skip to content
Back to search

bricks

Component layer for AI agents: implementation-aware contracts for building project-native interface components.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kostja94--bricks/badge.svg)](/listings/kostja94--bricks)

HTML

<a href="/listings/kostja94--bricks"><img src="/api/listings/kostja94--bricks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 180 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Bricks: Component Layer for AI Agents
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  3. [![GitHub stars](https://img.shields.io/github/stars/kostja94/bricks)](https://github.com/kostja94/bricks/stargazers)
  4. [![Last commit](https://img.shields.io/github/last-commit/kostja94/bricks)](https://github.com/kostja94/bricks/commits/main)
  5. Bricks gives coding agents implementation-aware contracts for building and maintaining interface components that belong in an existing product, codebase, and design system.
  6. It helps an agent understand a component's responsibility, context, variants, content, interaction states, technical boundary, and verification requirements before writing code.
  7. ## Install
  8. ```bash
  9. npx skills add kostja94/bricks --skill component-builder
  10. ```
  11. Give the agent a bounded component task and the context needed to integrate it:
  12. ```text
  13. Use component-builder to build the footer for this bilingual SaaS site.
  14. 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.
  15. ```
  16. See the complete [Footer request example](examples/footer-request.md).
  17. ## Component Governance
  18. Choose the entry point by the requested outcome:
  19. | Skill | Outcome |
  20. |---|---|
  21. | `component-builder` | Build a missing component in its real page context |
  22. | `component-inventory` | Discover actual pages, components and inline UI; save or refresh the project component system document |
  23. | `component-auditor` | Analyze semantic duplicates and drift, align one family at a time, or implement confirmed reconstruction |
  24. | `component-cleanup` | Remove verified unused components, abandoned generated UI and migration leftovers with their exclusive support files |
  25. Install a governance entry point with `npx skills add kostja94/bricks --skill component-inventory` (substitute the required skill name).
  26. 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.
  27. 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.
  28. For example:
  29. ```text
  30. Use component-inventory to map every page and component in this repository.
  31. Save the relationships and coverage gaps in our existing component system document.
  32. Then use component-auditor in audit-only mode to propose consolidation by semantic family.
  33. ```
  34. ## Why Bricks Exists
  35. 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.
  36. 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.
  37. 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.
  38. ## What Bricks Is
  39. | Bricks provides | Bricks does not provide |
  40. |-----------------|-------------------------|
  41. | One maintained contract per component concept | A separate Skill for every visual style |
  42. | Semantic responsibility and ownership boundaries | A fixed React, Vue, or CSS component package |
  43. | Context-aware variants and expected states | A universal design system |
  44. | Integration and verification guidance | A gallery of interchangeable mockups |
  45. | Stable component IDs for Agent tooling | Permission to replace project conventions |
  46. 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.
  47. ## Component Coverage
  48. The catalog spans small primitives, content structures, conversion elements, and composed Agent interfaces:
  49. | Group | Representative components |
  50. |-------|---------------------------|
  51. | Navigation and orientation | Navigation Menu, Footer, Breadcrumb, Sidebar, Table of Contents |
  52. | Content and explanation | Article Content Layout, Author Bio, FAQ Section, How-to Section, Tabs, Accordion |
  53. | Conversion and trust | CTA, Newsletter Signup, Comparison Table, Testimonials, Trust Signals |
  54. | Layout and presentation | Card, Grid, List, Masonry, Carousel, Modal, Announcement Banner |
  55. | Agent and tool interfaces | Task Input, Conversation, Chat Panel, Agent Workspace, CMS Editor Workspace |
  56. 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.
  57. ## From Request to Integrated Component
  58. The `component-builder` does not begin with a preferred library or visual treatment.
  59. 1. It inspects the page, nearby components, tokens, dependencies, data model, responsive conventions, and tests.
  60. 2. It identifies the canonical component concept, user task, surface, and ownership boundary.
  61. 3. It loads only the matching component reference and shared quality gates.
  62. 4. It selects a variant from real content and context.
  63. 5. It reuses the project's primitives and implements required states and interactions.
  64. 6. It verifies the component inside its actual page, not only in an isolated preview.
  65. 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.
  66. ## Context Matters
  67. The same component identity changes meaning across surfaces and pages.
  68. - A public marketing Footer organizes product, resource, company, and legal destinations.
  69. - An authenticated application Footer may be absent or reduced to operational links.
  70. - A documentation Sidebar needs hierarchy, active state, deep navigation, and narrow-screen behavior.
  71. - A dashboard Sidebar must also account for permissions, workspaces, collapsed states, and task frequency.
  72. Bricks records these contextual decisions without turning every combination into a new component name.
  73. ## Working With Pagina
  74. [Pagina](https://github.com/kostja94/pagina) and Bricks operate at different levels:
  75. ```text
  76. Pagina defines the complete page contract
  77. |
  78. v
  79. Pagina recommends required component concepts
  80. |
  81. v
  82. Bricks guides project-native component construction
  83. |
  84. v
  85. The target repository owns the final code and design system
  86. ```
  87. 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.
  88. ## Boundaries
  89. 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.
  90. Component governance handles existing UI through separate inventory, audit and cleanup skills. Cleanup is bounded to components and their support assets; whole-codebase cleanup and dependency upgrades are outside its scope. Bricks does not claim performance, accessibility, compliance, or conversion outcomes that were not actually verified in the target project.
  91. ## Repository Model
  92. ```text
  93. skills/component-builder/
  94. SKILL.md component construction entry point
  95. references/
  96. workflow.md shared construction workflow
  97. quality-gates.md component acceptance criteria
  98. pagina.md page-versus-component boundary
  99. components/ one reference per component concept
  100. skills/component-inventory/ discovery workflow and project document template
  101. skills/component-auditor/ semantic decisions and confirmed migration
  102. skills/component-cleanup/ component retirement and supporting-asset cleanup
  103. catalog/components.json machine-readable component concept catalog
  104. schemas/component-reference.schema.json
  105. scripts/validate.mjs deterministic checks
  106. examples/ realistic invocation examples
  107. ```
  108. References describe semantic responsibility, contexts, variants, constraints, and verification. They may include implementation suggestions where useful, but they do not prescribe a single stack or visual result.
  109. ## Maintenance Ownership
  110. | Maintained subject | Owner |
  111. |---|---|
  112. | Component concepts and implementation contracts | Existing component references linked by `catalog/components.json` |
  113. | Source discovery and coverage rules | [Inventory workflow](skills/component-inventory/references/workflow.md) |
  114. | Generated project document structure | [Component system template](skills/component-inventory/assets/component-system.template.md) |
  115. | Semantic consolidation and migration decisions | [Audit workflow](skills/component-auditor/references/workflow.md) |
  116. | Component deletion evidence and retirement | [Cleanup workflow](skills/component-cleanup/references/workflow.md) |
  117. Skill entry points route work; references maintain detailed rules, and the template defines the output fields. Project-specific contracts, consumer relationships and progress stay in the target project's existing component system document. Content facts remain in their original source; task chronology stays in its task tracker. Generated appendices declare their source revision and are refreshed from that source rather than hand-maintained in parallel.
  118. Public releases contain generic guidance and fictional examples only. Preserve the repository's public author and project links, but exclude client identities, internal URLs, workstation paths, credentials and copied project decisions. Bricks must run without access to the author's local knowledge or execution folders. Retired execution playbooks must not remain parallel maintained copies; external indexes may locate Bricks without duplicating its workflow rules.
  119. ## Development
  120. ```bash
  121. npm test
  122. ```
  123. Validation checks catalog IDs and classification fields, component reference file existence, Skill entry-point names and descriptions, and local Markdown file links. It does not prove schema conformance, semantic correctness, runtime behavior or production readiness.
  124. ## License
  125. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.