adobe / adobe/spectrum-design-data
Spike: Bikeshed spec prototype evaluation
- Dominant language
- Rust
- Stars
- 153
- Forks
- 35
- Avg merge
- 7h 54m
- Merged PRs (30d)
- 111
Description
Evaluate [Bikeshed](https://github.com/speced/bikeshed) as an alternative spec authoring tool by building a working prototype on a personal repo (\`garthdb/design-data-spec\`) that publishes to GitHub Pages.
The prototype renders a representative slice of the spec (index, token-format, taxonomy, agent-surface chapters + a rules excerpt) via Bikeshed and publishes to \`https://garthdb.github.io/design-data-spec/\`. Once live, we compare it against the current 11ty-built spec on six criteria to decide whether to migrate, cherry-pick features, or shelve.
## Decision criteria
1. **Visual quality** — does the output look right for a vendor spec, or too W3C?
2. **Markdown fidelity** — does the include-based approach render existing prose correctly?
3. **Authoring tax** — how much extra markup do \`\` / \`[=term=]\` autolinks cost?
4. **Cross-ref ergonomics** — is \`[=token=]\` autolinking better than manual hrefs?
5. **Build time / CI complexity** — Bikeshed-only GH Action vs. current multi-job 11ty pipeline
6. **URL & deep-link story** — is single-page-with-fragments acceptable for our use cases?
Deliverable: evaluation doc (sub-issue #7 below) with concrete findings per criterion drives the migrate/cherry-pick/shelve decision.
Contributor guide
Research direction
Start with the prototype target in garthdb/design-data-spec and the published GitHub Pages URL, then compare its representative index, token-format, taxonomy, agent-surface, and rules chapters with the current 11ty-built spec. Record concrete findings against the six listed criteria in the evaluation doc from sub-issue #7, ending with a migrate, cherry-pick, or shelve recommendation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, markdown
- Domain
- build-system, documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100