adobe / adobe/spectrum-design-data

Phase 3: Build Glossary Web Viewer (GitHub Pages)

Open
#662 1 comment 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Rust
Stars
153
Forks
35
Avg merge
7h 54m
Merged PRs (30d)
111

Description

## Overview

Create a static, searchable web interface for browsing the Spectrum Design System Glossary, deployed to GitHub Pages.

**Related**: RFC Discussion #661 - Spectrum Design System Glossary

## Deliverables

### 1. Package Structure
- Create `docs/spectrum-glossary/` package
- Add `package.json`, `moon.yml`, build scripts
- Follow pattern from existing docs sites (`docs/s2-tokens-viewer`)

### 2. Core Features
- **Search & Filter**: Full-text search across all terms
- **Category Navigation**: Browse by registry type (sizes, states, variants, etc.)
- **Term Detail View**: Show all metadata
- Definition (superordinate, description, characteristics)
- Platform variations
- Sources and references
- Related terms with cross-links
- **Export**: JSON, CSV download options
- **Deep Linking**: Direct URLs to specific terms
- **Mobile Responsive**: WCAG 2.1 AA compliant

### 3. Build System
- `scripts/build-glossary.js` - Compile registry data into static HTML
- Generate static API files in `api/v1/` directory
- Integrate with existing build pipeline

### 4. GitHub Pages Deployment
- Configure repository for Pages
- Create `.github/workflows/deploy-glossary.yml`
- Auto-deploy on changes to registry
- Target URL: `https://adobe.github.io/spectrum-design-data/glossary/`

### 5. Integration
- Link from existing Spectrum documentation
- Embed help links in Component Options Editor
- Reference in naming guide documentation

## Dependencies

- ✅ Phase 1: Enhanced schema and content (Completed in feat/add-design-system-registry branch)
- ✅ Phase 2: Platform extensions (Completed in feat/add-design-system-registry branch)

## Acceptance Criteria

- [ ] Glossary accessible at GitHub Pages URL
- [ ] All 179 registry terms searchable and browsable
- [ ] Mobile-responsive design
- [ ] WCAG 2.1 AA accessibility compliance
- [ ] Auto-deployment working via GitHub Actions
- [ ] Export functionality (JSON, CSV) working
- [ ] Load time < 2 seconds
- [ ] Search results < 500ms

## Estimated Effort

2-3 weeks

## Related

- RFC: https://github.com/adobe/spectrum-design-data/discussions/661
- Implementation Status: `GLOSSARY_IMPLEMENTATION_STATUS.md`

Contributor guide

Open the contributing guide

Research direction

Read GLOSSARY_IMPLEMENTATION_STATUS.md and inspect the existing docs/s2-tokens-viewer pattern first. Then trace the registry data into scripts/build-glossary.js, the api/v1/ output, and .github/workflows/deploy-glossary.yml. Done means the 179 terms are searchable, browsable, exportable, accessible, responsive, and deployed at the stated GitHub Pages URL.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, html, javascript
Domain
ci-cd, documentation, frontend, web-dev
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.