Skip to content

Commit b3d55dc

Browse files
mgiffordmgifford
authored
Merge pull request #9 from mgifford/copilot/add-styles-md-file
Add STYLE.md: design and content standards
2 parents 92fd933 + 084a4d3 commit b3d55dc

1 file changed

Lines changed: 352 additions & 0 deletions

File tree

‎STYLE.md‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
# STYLE.md: Design and content standards
2+
3+
This file defines how content is written, designed, and published in this project.
4+
It governs both the live web app and the repository documentation, and is the
5+
authoritative reference for both humans and AI coding agents contributing to
6+
EchoLocate.
7+
8+
---
9+
10+
## Scope: documentation files vs. the web app
11+
12+
This project has two surfaces that share the same standards:
13+
14+
| Surface | Files | Audience |
15+
| :--- | :--- | :--- |
16+
| **Web app (GitHub Pages)** | `index.html`, `style.css`, `app.js`, `sw.js` | Public users running live captioning sessions |
17+
| **Repository documentation** | `README.md`, `AGENTS.md`, `STYLE.md`, `ACCESSIBILITY.md`, `FEATURES.md` | Contributors, adopters, and AI agents reading files directly on GitHub |
18+
19+
**What applies to both surfaces:**
20+
- Section 2 — Content and voice standards (plain language, active voice, sentence-case headings, American English, abbreviations, content structure)
21+
- Section 4 — Accessibility and semantic logic (heading hierarchy, alt text, link text)
22+
- Section 5 — AI agent instructions
23+
- Section 6 — Content governance
24+
25+
**What applies to the web app only:**
26+
- Section 3 — Design foundations (color tokens, typography, breakpoints, layout)
27+
28+
Even though documentation files are rendered as plain Markdown rather than styled
29+
HTML, they share the same voice, tone, and heading conventions as the app UI. This
30+
keeps the project a unified whole for every reader, regardless of which surface they
31+
encounter first.
32+
33+
---
34+
35+
## 1. Core philosophy
36+
37+
We design for the reader and the user, not the institution. The goal is to reduce
38+
cognitive load through consistency, clarity, and radical accessibility.
39+
40+
EchoLocate exists to provide live, private, in-browser captions for deaf and
41+
hard-of-hearing users. Every design and writing decision must serve that purpose.
42+
43+
1. **Reader-first.** Start with the user's need, not the technical structure.
44+
2. **Plain language.** If a 12-year-old cannot understand it, it is a barrier.
45+
3. **Inclusive by default.** See [ACCESSIBILITY.md](./ACCESSIBILITY.md) for all
46+
interaction and visual standards.
47+
4. **Privacy-first.** All audio and transcript processing stays in the browser.
48+
Nothing is sent to a server or third-party cloud service.
49+
5. **Consistency is trust.** AI agents and humans must use the same tokens, patterns,
50+
and vocabulary.
51+
6. **Radically open.** Work transparently; share methods and findings openly.
52+
53+
---
54+
55+
## 2. Content and voice standards
56+
57+
Derived from UK GDS and Digital.gov plain language standards.
58+
59+
### 2.1 Voice and tone
60+
61+
We use an **authoritative peer** tone: professional and knowledgeable, but accessible
62+
and supportive.
63+
64+
| Context | Tone | Strategy |
65+
| :--- | :--- | :--- |
66+
| **Onboarding / labels** | Encouraging | Focus on the benefit to the user |
67+
| **Technical / reference** | Precise | Be unambiguous; explain "why" if a rule is complex |
68+
| **Error states** | Calm / helpful | Do not blame the user; provide a clear path forward |
69+
| **Privacy / legal** | Clear and grounded | Use plain statements; avoid legalese |
70+
71+
### 2.2 Plain language and word choice
72+
73+
AI agents must prioritize these substitutions:
74+
75+
| Avoid | Use instead |
76+
| :--- | :--- |
77+
| Utilize / leverage | Use |
78+
| Facilitate / implement | Help / carry out |
79+
| At this point in time | Now |
80+
| In order to | To |
81+
| Notwithstanding | Despite / even though |
82+
| Requirements | Rules / what you need |
83+
84+
### 2.3 Grammar and mechanics
85+
86+
- **Active voice:** "The scanner checks the link" — not "The link is checked by
87+
the scanner."
88+
- **Sentence case:** Use sentence case for all headings and UI labels. "Save and
89+
continue" — not "Save and Continue."
90+
- **Lists:** Use bullets for unordered items. Use numbered lists only for sequential
91+
steps.
92+
- **Oxford comma:** Always use the serial comma in lists of three or more.
93+
94+
### 2.4 Spelling convention
95+
96+
This project uses **American English** as its default spelling standard.
97+
98+
| Variant | Example spellings | When to use |
99+
| :--- | :--- | :--- |
100+
| **American English** (default) | color, center, optimize, behavior | All documentation and UI text in this project |
101+
102+
> **AI agents:** Always apply American English spelling rules throughout all
103+
> documents and UI strings.
104+
105+
### 2.5 Abbreviations, numbers, and dates
106+
107+
#### Abbreviations
108+
109+
- Spell out an abbreviation on first use, then use the short form: "Web Content
110+
Accessibility Guidelines (WCAG)."
111+
- Do not use periods in acronyms: "HTML," "CSS," "ASR" — not "H.T.M.L."
112+
- Avoid jargon-only abbreviations without explanation unless writing for a
113+
specialist audience.
114+
115+
#### Numbers
116+
117+
| Context | Rule | Example |
118+
| :--- | :--- | :--- |
119+
| **In body text** | Spell out one through nine; use numerals for 10 and above | "three speakers," "12 cards" |
120+
| **Starts a sentence** | Always spell out | "Six speaker lanes are supported." |
121+
| **Percentages** | Use numerals and the % symbol | "4.5% contrast ratio" |
122+
| **Versions and technical values** | Always use numerals | "WCAG 2.2," "font-size: 1rem" |
123+
124+
#### Dates
125+
126+
- Use **ISO 8601** for machine-readable dates: `2025-06-01`.
127+
- Use **spelled-out months** for human-readable dates: "June 1, 2025."
128+
- Do not use all-numeric dates that could be ambiguous across locales (01/06/2025).
129+
130+
### 2.6 Attribution and citation
131+
132+
When quoting, adapting, or referencing external work in documentation:
133+
134+
- **Quote directly** only when the original wording matters and cannot be improved.
135+
Block-quote passages over three lines.
136+
- **Paraphrase** when the idea is what matters. Paraphrasing does not remove the
137+
need to credit the source.
138+
- **Credit the source** inline or in a references section.
139+
- **Link to the source** rather than reproducing large portions of external content.
140+
- **Do not reproduce** entire copyrighted works, style guides, or specifications.
141+
Reference them and link to the canonical source.
142+
143+
> **AI agents:** Do not reproduce large passages from external style guides or
144+
> specifications verbatim. Summarize, paraphrase, and link to the canonical source.
145+
146+
### 2.7 Content structure and document types
147+
148+
Different document types follow different patterns. Use the appropriate structure
149+
rather than treating all Markdown files the same.
150+
151+
| Document type | Purpose | Structure pattern |
152+
| :--- | :--- | :--- |
153+
| **Reference** (STYLE.md, ACCESSIBILITY.md) | Authoritative rules; consulted, not read cover-to-cover | Numbered sections, tables, bullet rules |
154+
| **Guide or how-to** (README.md, INSTALL.txt) | Step-by-step walkthrough for a specific audience | Numbered steps, "you" voice, outcome-focused |
155+
| **Feature catalog** (FEATURES.md) | Comprehensive technical inventory | Categorized sections, file paths, option tables |
156+
| **Agent instructions** (AGENTS.md) | Working agreements for AI contributors | Short rules, checklists, concise facts |
157+
158+
Rules that apply to all document types:
159+
160+
- Use heading levels in order (`#` then `##` then `###`). Do not skip levels.
161+
- Open each document with a one-sentence purpose statement.
162+
- Keep paragraphs short: three to five sentences is a good maximum.
163+
- Prefer short sentences over long, complex ones.
164+
165+
---
166+
167+
## 3. Design foundations (web app only)
168+
169+
These rules apply to `index.html`, `style.css`, `app.js`, `sw.js`, and any UI
170+
element rendered in the browser. They do not govern plain Markdown documentation.
171+
172+
### 3.1 Design tokens
173+
174+
The canonical values live in `style.css` under `:root` (dark defaults) and
175+
`[data-theme="light"]` (light overrides). Agents must read and update only these
176+
tokens when changing the visual design; never hardcode hex values outside
177+
`style.css`.
178+
179+
#### Dark theme (default — `:root`)
180+
181+
| Token | Value | Role |
182+
| :--- | :--- | :--- |
183+
| `--bg-page` | `#000000` | Base page background |
184+
| `--bg-surface` | `#0d0d0d` | Surface-level backgrounds (header, footer) |
185+
| `--bg-card-a` | `#071524` | Speaker A card background (blue-tinted) |
186+
| `--bg-card-b` | `#160826` | Speaker B card background (purple-tinted) |
187+
| `--accent-a` | `#4dabf7` | Speaker A accent color (sky blue) |
188+
| `--accent-b` | `#cc5de8` | Speaker B accent color (vivid purple) |
189+
| `--text-primary` | `#f1f3f5` | Primary readable text |
190+
| `--text-muted` | `#868e96` | Supporting / secondary text |
191+
| `--text-interim` | `rgba(241,243,245,0.45)` | In-progress speech text |
192+
| `--warning` | `#ffd43b` | Warning states |
193+
| `--danger` | `#ff6b6b` | Error / destructive states |
194+
| `--success` | `#69db7c` | Success / positive states |
195+
196+
#### Light theme overrides (`[data-theme="light"]`)
197+
198+
| Token | Value | Role |
199+
| :--- | :--- | :--- |
200+
| `--bg-page` | `#f0f2f5` | Base page background |
201+
| `--bg-surface` | `#ffffff` | Surface-level backgrounds |
202+
| `--bg-card-low` | `#e8f4fd` | Low-confidence card background |
203+
| `--bg-card-mid` | `#fef9e7` | Mid-confidence card background |
204+
| `--bg-card-high` | `#f5e6ff` | High-confidence card background |
205+
| `--text-primary` | `#1a1a2e` | Primary readable text |
206+
| `--text-muted` | `#5c6370` | Supporting / secondary text |
207+
| `--danger` | `#c92a2a` | Error / destructive states |
208+
| `--success` | `#2f9e44` | Success / positive states |
209+
| `--warning` | `#e67600` | Warning states |
210+
211+
Both themes must meet WCAG 2.2 AA contrast requirements. Verify contrast for any
212+
new color using a tool such as the
213+
[WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/).
214+
215+
### 3.2 Typography
216+
217+
- **Font stack:** `'Segoe UI', system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif`
218+
(defined as `--font` in `style.css`).
219+
- **Font scaling:** Use `rem` units. Never use `px` for font sizes.
220+
- **Line length:** 45–75 characters per line for prose blocks.
221+
- **Line height:** Minimum `1.6` for body text.
222+
- **Text alignment:** Use left-aligned text for transcript cards and UI labels.
223+
Avoid `text-align: justify`.
224+
- **Capitalization:** Use CSS `text-transform` for decorative uppercase styling.
225+
Do not write uppercase text directly in HTML source.
226+
227+
### 3.3 Responsive design (mobile-first)
228+
229+
Write base CSS for the smallest screen first, then enhance with `min-width` queries.
230+
231+
| Layer | Breakpoint | Intent |
232+
| :--- | :--- | :--- |
233+
| **Mobile** | `0`–`599px` (base, no query) | Single-column, touch targets >= 44x44 px |
234+
| **Tablet** | `min-width: 600px` | Two-column lane layouts where content benefits |
235+
| **Desktop** | `min-width: 900px` | Multi-lane grids, wider prose |
236+
237+
- **Never block zoom.** The viewport meta tag must not include `maximum-scale=1` or
238+
`user-scalable=no`. Users must be able to scale the page freely.
239+
240+
### 3.4 User-preference media queries
241+
242+
| Query | Status | Implementation |
243+
| :--- | :--- | :--- |
244+
| `prefers-color-scheme` | — | Theme is user-controlled via the Theme button; `[data-theme]` attribute overrides OS preference |
245+
| `prefers-reduced-motion` | Required | Remove or reduce transitions and animations |
246+
| `prefers-contrast` | Planned | Not yet implemented |
247+
| `forced-colors` | Planned | Not yet implemented |
248+
| `print` | Recommended | Hide controls and decorative elements; render transcript text at >= 12pt |
249+
250+
### 3.5 UI component conventions
251+
252+
- **Buttons:** Use `<button>` elements with visible focus rings. Never use `<div>` or
253+
`<span>` as interactive controls.
254+
- **Speaker lanes:** Each lane has a header with a speaker label and controls. Lane
255+
color is drawn from the speaker's assigned accent token.
256+
- **Transcript cards:** Cards display speaker label, timestamp, confidence meter, and
257+
transcript text. Low-confidence cards receive additional visual marking.
258+
- **Interim speech strip:** Displays in-progress text with `role="status"` and
259+
`aria-live="polite"`. Uses `--text-interim` for visual distinction.
260+
- **Security / privacy notice:** Styled with `--warning` border. Must remain visible
261+
until explicitly dismissed by the user.
262+
- **Sanitization:** Always use `escapeHtml()` in `sw.js` before inserting any
263+
user-controlled or externally sourced string into a rendered HTML fragment.
264+
265+
---
266+
267+
## 4. Accessibility and semantic logic
268+
269+
These rules apply to **both surfaces**. EchoLocate exists to serve deaf and
270+
hard-of-hearing users; our own implementation must meet or exceed the same
271+
accessibility standards we advocate for.
272+
273+
- Use heading levels in order: `h1` then `h2` then `h3`. Do not skip levels.
274+
- Write descriptive link text. "Read more about plain language" — not "click here."
275+
- Every image needs meaningful alt text. Decorative images use `alt=""`.
276+
- Use `aria-label` on landmark elements when the role is ambiguous.
277+
- Minimum color contrast: 4.5:1 for body text, 3:1 for large text and UI components.
278+
- Do not convey information by color alone. Always pair color with a secondary
279+
indicator: an icon, label, pattern, or text.
280+
- Ensure touch and click targets are at least 44x44 pixels for primary interactive
281+
elements.
282+
- Use underlines only for links, not for decorative or non-link text.
283+
- Provide a "skip to main content" skip link at the start of each page so keyboard
284+
users can bypass repeated navigation.
285+
- Live transcript lanes must use `role="log"` so additions are announced by screen
286+
readers.
287+
- The interim speech strip must use `role="status"` and `aria-live="polite"`.
288+
289+
See [ACCESSIBILITY.md](./ACCESSIBILITY.md) for the full accessibility commitment,
290+
conformance target (WCAG 2.2 AA), and manual test checklist.
291+
292+
---
293+
294+
## 5. AI agent instructions
295+
296+
These rules apply to both surfaces. Agents editing documentation and agents
297+
generating UI code must follow all of them.
298+
299+
- Read [AGENTS.md](./AGENTS.md) before making any change to this repository.
300+
- Identify which surface is being edited (web app or documentation) and apply the
301+
correct rule set.
302+
- Never override [ACCESSIBILITY.md](./ACCESSIBILITY.md) constraints.
303+
- Never add network transmission of audio or transcript data. All processing must
304+
remain client-side.
305+
- Use American English throughout.
306+
- Keep changes scoped to the minimum necessary to fulfill the user's request.
307+
- Verify all cross-file references resolve before committing.
308+
- When rendering HTML in `sw.js`, always use `escapeHtml()` for any user-controlled
309+
or externally sourced data.
310+
- Use UTF-8 encoding only. Do not use smart quotes, em dashes, or Windows-1252
311+
characters in source files.
312+
- Use absolute or project-relative paths (for example, `app.js`, `vendor/htmx/`),
313+
never bare filenames without context.
314+
- Before committing, verify `node --check app.js` and `node --check sw.js` both
315+
pass with no errors.
316+
- Preserve theme parity: any new UI component must be readable in both dark and
317+
light modes.
318+
- Do not silently override or quietly contradict rules in this file. If a requested
319+
change would conflict with an existing rule, surface the conflict and ask for
320+
clarification before proceeding.
321+
322+
---
323+
324+
## 6. Content governance
325+
326+
These rules describe how this style guide itself is maintained and updated.
327+
328+
- **Ownership:** The project maintainer is responsible for keeping these standards
329+
current. Contributors may propose changes via pull request.
330+
- **Conflict resolution:** When two rules conflict, the more specific rule takes
331+
precedence. When this file conflicts with ACCESSIBILITY.md, ACCESSIBILITY.md wins.
332+
- **Versioning:** Changes to standards that affect existing content should be noted
333+
in commit messages.
334+
- **Review cycle:** Standards should be reviewed at least once per year or when a
335+
significant feature or platform change occurs.
336+
- **Deprecation:** Remove outdated rules rather than leaving contradictions. A rule
337+
that no longer applies should be deleted, not commented out.
338+
339+
---
340+
341+
## 7. References
342+
343+
- [Plain Language Guidelines — Digital.gov](https://www.plainlanguage.gov/guidelines/)
344+
- [GOV.UK Content Design Guide](https://www.gov.uk/guidance/content-design/writing-for-gov-uk)
345+
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
346+
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
347+
- [Nielsen Norman Group: Ten Usability Heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/)
348+
- [STYLES.md reference template](https://github.com/mgifford/STYLES.md)
349+
- [ACCESSIBILITY.md](./ACCESSIBILITY.md)
350+
- [AGENTS.md](./AGENTS.md)
351+
- [FEATURES.md](./FEATURES.md)
352+
- [README.md](./README.md)

0 commit comments

Comments
 (0)