adobe / adobe/spectrum-design-data

Spike: Bikeshed spec prototype evaluation

Open
#1,006 0 comments 0 reactions 0 assignees View on GitHub
spec-tooling
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.