Open questions and tensions
A standard that hides its unsettled parts is harder to argue with and easier to be wrong about. These are published unresolved, in the order they would change what the rest of this site says.
Seven open questions
Is alignment for humans or for machines?
The argument this site makes is that aligned columns turn a class body into a table, and that this is a machine-readability decision in a codebase 61% written by an agent, not an aesthetic one.
It is a claim, not an established fact, and it is falsifiable. The cost is real and
measured — diff noise, and permanently forgoing black, prettier and
every formatter that exists. The benefit has never been measured by anyone. The honest position
is: it costs this, it buys scanability, we think the trade is worth it here, and here are the
numbers so you can disagree.
Where it bites: the house style · CSS
Is rule 9 — no _private — Python-only?
895/992 = 91% (97 violations) in Python,
and the JavaScript uses _select, _update, _current as a
matter of course.
The rule set does not say, so in practice the rule is neither enforced nor retired — the worst of the three available states, because nobody can tell whether a violation is a mistake. Two acceptable answers: mark it Python-only, or change one of the two languages. Anything is better than leaving it ambiguous.
Where it bites: rule 9 · JavaScript formatting
Which design-token prefix?
--bg-panel, --sg-surface, --sgl-tab-h. Three families
for one token system, with no documented meaning for the distinction.
Pick one, or document what each means. The numbered ramps are the good part —
--text-1..4, --sg-sp-1..4, --shadow-1..2 — and should be
kept either way: a bounded ramp means there is a right answer to “which grey?”.
Where it bites: CSS tokens
Should a public coding standard document a dev. host?
Every component example imports its base class and its tokens from
dev.tools.sgraph.ai. Redacting it teaches nothing — a component example without
its import URL is not an example. Publishing it documents a development host as a canonical
public contract.
This site publishes it, deliberately. It is a public CDN serving public component
code and it is visible in any rendered page's network tab. But the dev. prefix is
a durability risk for something being written down as a standard, and the decision should be
revisited rather than inherited. What else was
redacted, and what was not →
Where it bites: the versioned CDN
Does runtime type safety replace static analysis, or defer it?
Type_Safe catches shape errors at construction, which is a better fit for
generated code than a checking pass the generator may never run. It does not catch
unreachable code, unused imports, shadowed names, or a typo in a branch that never executes.
The honest answer is that it replaces one kind of checking and the other kind is simply
absent. That is why the shipped ruff config selects the pyflakes category and
little else: it is aimed precisely at the gap rather than at re-litigating the type system.
Is “no mocks, no patches” affordable outside this estate?
It works here: 4,785 tests in 81 seconds, because Type_Safe objects are
cheap to build and there is an in-memory composition path for the service.
Whether it generalises is a real question. A codebase whose dependencies are a database, a
payment provider and three HTTP services has no equivalent of
register_playwright_service__in_memory() without building one first — and building
one is the actual cost of the position. This site does not assume it generalises.
Where it bites: the testing rules
Does the no-build-step position survive the next dependency?
50 files, one level of imports, and no CommonJS-only package yet. The position is genuinely strong today and it has a named breaking point: a dependency graph deeper than one level, or a package that only ships as CJS.
Neither has happened, which is not the same as neither happening. Worth deciding in advance what the answer is, because deciding it under deadline is how a build step arrives permanently.
Where it bites: the no-build-step trade
Do the two claimed CI guards exist?
Rules 10 and 16 are each described as having a CI guard behind them. Neither appears in the
source's own table of guards, which lists five and describes tests/ci/ as the
entire enforcement surface.
It is probably a documentation gap rather than a missing guard. But the one guard in that table that was supposed to hold a line had never worked, so the benefit of the doubt is not free here. Both rules are marked ❓ guard claimed, unlisted until somebody looks.
Where it bites: what is not enforced · rules 10 and 16
Six tensions
- 31 written rules and zero enforcement. Compliance of 100%, 989/992 = 99.7% and 299/302 = 99%, achieved by discipline rather than tooling. That is impressive and it is fragile — and the one guard that was supposed to hold a line had never worked.
- A style guide for five languages that documents one. The other four are maintained by whoever last read the neighbouring file.
- Alignment is either the best or the worst convention here. No formatter in the industry will produce it, so adopting it means never adopting formatter-driven tooling at all. A real, permanent cost accepted for an unmeasured benefit.
- The rules were written for agents and published to none.
.claude/CLAUDE.mdis read by every session and by no human who has not gone looking for it. - Runtime validation is a good fit for generated code and a poor substitute for a linter. Both are true. The estate has the first and not the second.
- The most interesting page is the least verifiable. /for-agents/ is the original contribution here, and its central claim is asserted from design intent and commit statistics rather than from measurement. It is published as a position with the evidence attached.
Seven loose ends, an hour each
- Confirm whether a second theme file exists. The token names suggest dark-first; the survey could not verify a light theme, so the CSS page does not claim one.
- Count the components outside the sg-compute tree. The CDN serves
base,tokens,vault-clientandvault-write— is there a wider registry? - Check whether
SgComponent's source is public. Every example imports it. If it is not readable, the pattern on this site cannot be adopted by anyone outside the estate, which would make the JavaScript page a description rather than a standard. - Resolve the
sp-cli:event namespace — 23 files, and renaming it breaks external listeners. - Decide the semicolon rule and reformat the older tree to match the newer one.
- Write down the
set -euo pipefailrule — 2 of 5 files, three different forms, no rule. - Extract the four
tests/ci/guards into a reusable module. They are the pattern the enforcement page recommends, and they currently live in exactly one repository.
And seven things nobody has written yet
| # | Item | State |
|---|---|---|
| G1 | Rules for JavaScript, CSS, HTML and Bash | 14 candidates published; none is a rule yet |
| G2 | A human-readable style guide | This site. Shipped |
| G3 | The for-agents argument | Shipped, as a position |
| G4 | A worked “add a new spec” walkthrough | Not written. The mechanisms are real; the tutorial is not |
| G5 | A worked “add a new component” walkthrough | Not written |
| G6 | Golden rendered shell files, one per Section__* | Not written. The test that would produce them is shipped |
| G7 | A decision-record format | Not written. Rules 14, 15 and 21 are ADRs in all but name — they cite their own precedent |