Skip to content

fix(docs): 'docs build' shouldn't dump empty 571-line boilerplate when no CSpecs exist #16

Description

@noemuch

Problem

Running `bridge-ds docs build` on a fresh-scaffolded repo (KB extracted, zero CSpecs) produces ~571 lines of doc per component × 92 components = a forest of empty Handlebars sections ("How to use", "When NOT to use", "Props", "Variants", "Do/Don't", "Accessibility" — all blank placeholders).

The user has no signal that the docs are empty by design. They ship boilerplate that has to be wiped.

Root cause

The docs renderer falls back to "dump everything generic" when no CSpec is bound to a component. CSpecs are produced organically via the `make` / `fix` / `done` cycle, so on day one of a fresh repo there are zero of them.

Fix (proposed)

Hard-fail with guidance when zero CSpecs exist:

```
$ bridge-ds docs build
Error: No CSpecs found in knowledge-base/cspecs/

Bridge docs grow organically as you design. To document a component:

  1. bridge make Button → produces a CSpec + Figma output
  2. bridge done → ships + archives the CSpec
  3. bridge-ds docs build → renders docs for that component

Run 'bridge make ' first.
```

Skip components without a CSpec when at least one exists. The output should only contain components that have a CSpec. No template dumps.

Found in

Spectra repo, fresh `setup bridge` + `docs build` with v5.1.0 (2026-04-16).

Acceptance

  • 0 CSpecs → exits non-zero with the guidance above, generates nothing
  • N CSpecs → renders exactly N component docs, silently skips the rest
  • No empty placeholder sections in any rendered doc

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions