docs: honest science rewrite, Marketplace-first README, CONTRIBUTING.md - #17
Merged
Conversation
README: "The Science" now separates dominant wavelength (576–611 nm, true of every hex) from spectral content (neutrals still light the blue subpixel, ~23–27 % of their light vs 33 % for white); replaces the rod-impact table with the CIE 1951 V′(λ) curve; states the real benefits (low text luminance, no blue defocus, lower melanopic stimulus, comfort) and retracts the dark-adaptation-protection claim (red-only variants remain on the roadmap). Marketplace-first ordering, WCAG+APCA side by side, CVD section, bold-weight wording fixed (theme bold is 700; 450 is editor.fontWeight), fontVariations in recommended settings, melanopic/Night Shift advice, FAQ rewritten. Contributor docs move to CONTRIBUTING.md and grow into a verifier contract and change procedures. package.json description drops the adaptation claim. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Reviewer's GuideRewrites and reorders the README to be Marketplace-first and scientifically precise about what the palette actually does, updates all related descriptions and accessibility sections, and moves contributor/build documentation into a new CONTRIBUTING.md while keeping the verifier-owned tables in sync. Flow diagram for the contributor palette-change and verification pipelineflowchart TD
C[Edit palette in themes/_src/variants name.yaml or base.yaml]
B[npm run build:themes]
V[npm run verify]
R[node scripts/verify-palette.mjs --write-readme]
T[npm test]
P[npx @vscode/vsce package]
G[Commit regenerated themes/*.json and README tables]
C --> B --> V
V -->|all checks pass| R
R --> T --> P --> G
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In the Recommended Settings snippet,
"editor.minimap.enabled": trueunder the "Reduce visual noise" section reads like a copy/paste oversight; if the intent is to reduce clutter, consider setting this tofalseor clarifying why the minimap is enabled there. - The README has become quite long and dense, especially around the science and verifier details; consider moving some of the more technical explanations (e.g., exact rod/melanopic ratios, verifier policy details) into a separate
docs/page and linking it, so the Marketplace-facing README stays focused on user-facing behavior and setup.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the Recommended Settings snippet, `"editor.minimap.enabled": true` under the "Reduce visual noise" section reads like a copy/paste oversight; if the intent is to reduce clutter, consider setting this to `false` or clarifying why the minimap is enabled there.
- The README has become quite long and dense, especially around the science and verifier details; consider moving some of the more technical explanations (e.g., exact rod/melanopic ratios, verifier policy details) into a separate `docs/` page and linking it, so the Marketplace-facing README stays focused on user-facing behavior and setup.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
…ourcery on PR #17) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Owner
Author
|
Re Sourcery review:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0b0c9432e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The ultimate expression of vision science in a coding theme. Protect your eyes as your sessions extend for hours. Your eyes won't hate you. | ||
| <!-- hero: images/hero.png — added with the release pipeline (see docs/PUBLISHING.md) --> | ||
|
|
||
| Alone is a warm, low-luminance dark theme for people who code in dark rooms for hours. Every colour in it — syntax, UI chrome, terminal — has a dominant wavelength between 576 and 611 nm: gold, amber, olive, terracotta, dusty rose. There is no blue, no cyan, no purple, and no white text. Foregrounds sit well below the brightness of a typical dark theme, contrast is tuned with APCA rather than maxed out, and a verifier script fails the build if any of that drifts. |
There was a problem hiding this comment.
The shipped Alone Roman string colour #9C8B4A has a dominant wavelength of 575 nm according to the repository's own dominantWavelength implementation, and SCAN_MIN_NM intentionally accepts 575. Thus the claim that every colour is between 576 and 611 nm is already false for one advertised variant; change the lower bound to 575 or adjust the colour and verifier threshold.
Useful? React with 👍 / 👎.
|
|
||
| - **`themes/_src/base.yaml`** — the structural skeleton. Every key the variants share (shape, scopes, font styles, and any hex that happens to be identical across all variants) lives here as a literal. Every leaf that varies across variants is written as `${token.name}`. | ||
| - **`themes/_src/variants/<name>.yaml`** — per-variant bindings: `display`, `filename`, a `verify` block (which wavelength band the variant should pass and whether it's the "standard" used for the L\* ladder / README WCAG checks), and a `tokens:` block supplying the hex/alpha values for that variant's `${token.name}` references — plus the two font-style tokens `style.italic` (`italic` or `""`) and `style.semanticItalic` (`true`/`false`) that Alone Roman binds to "off". | ||
| Every meaning-carrying colour pair is checked under simulated protanopia and deuteranopia in all four variants (ΔE2000 ≥ 5 or a font-style difference), and the terminal's sixteen ANSI slots stay ≥ ΔE2000 10 apart. Tritanopia is not a concern for a palette with no blue axis. |
There was a problem hiding this comment.
For tritanopic users or terminal programs that emit bright ANSI colours, this answer promises guarantees the verifier does not provide: cvdRows computes pass/fail only from protan/deutan results, while the ANSI check slices the palette to the first eight normal slots. The current palette also violates the stated thresholds outside those checks—for example Types/Functions are about ΔE2000 4.5 under the existing tritan simulation, and Blue/BrightBlue are about 6.7—so either enforce tritan and all 16 slots or qualify this safety claim.
Useful? React with 👍 / 👎.
| - **APCA floors** — identifiers ≥ 60, syntax ≥ 40, Special/Strings ≥ 37, punctuation ≥ 28, comments ≥ 22 (Alone Soft carries its own floors in its variant file). | ||
| - **CVD** — the role pairs in `scripts/lib/theme-roles.mjs` must stay ΔE2000 ≥ 5 apart after protan and deutan simulation, or differ in font style. Alone Roman has no italic cue, so its pairs must pass on colour alone. | ||
| - **ANSI** — the eight normal terminal slots pairwise ΔE2000 ≥ 10. | ||
| - **Wavelength** — every hex in every variant must have a dominant wavelength inside the variant's declared band (or be a neutral). |
There was a problem hiding this comment.
When a contributor adds the planned red-only or red-amber variant, an out-of-band UI colour can still pass despite this contract: bandCheck is applied only to the ten LADDER_ROLES, while the scan over every hex merely requires dominant wavelength ≥575 nm. For example, an amber cursor in a red-only variant is outside that declared band but passes the whole-theme scan, so the guide should state the narrower scope or the verifier should apply the declared band to every chromatic hex.
Useful? React with 👍 / 👎.
…al ANSI slots) Addresses Codex review on PR #17: Alone Roman's string hex is 575 nm; tritan is not enforced; the ANSI bound covers slots 0-7; the whole-theme scan is a >=575 nm floor, not the declared band. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Plan step 6 of
docs/plans/2026-08-18-audit-remediation.md— make the README say what the palette actually does, in the order a Marketplace visitor reads it, and move contributor docs out.README
#0C0A09vs#000000. Numbers were recomputed from the 2.0.0 palette (scratch script, tristimulus approximation — labelled indicative).editor.fontWeightfor body text."editor.fontVariations": trueso a variable font really renders 450; Display: melanopic / OS warm-shift advice (Night Shift stacks with the palette).<!-- verify:… -->) untouched and re-rendered;npm run verifyreports README current.Elsewhere
CONTRIBUTING.md(new): layout, build commands, the verifier contract (every hard-fail check and threshold), palette-change / scope-addition / new-variant procedures, PR expectations. The README "Building the Themes (Contributors)" section moves there.package.jsondescription drops the dark-adaptation claim.Test plan
npm run check(incl. README-table drift check) green,npm test26/26#what-it-does-not-do,#display-recommendations,#theme-variants,CHANGELOG.md#future-plans)vsce lsunchanged (CONTRIBUTING.md is excluded by the*.mdrule)🤖 Generated with Claude Code
Summary by Sourcery
Rewrite the project documentation to present the theme accurately to users and provide a dedicated guide for contributors.
New Features:
Bug Fixes:
Enhancements:
Documentation:
Tests: