Rules and checks

Every rule in Principles is held in at least one of three ways (how a rule is held): the kit is its only implementation, a check measures it, or the design audit looks at it before a release. This chapter lists them all, by name.

Every rule, and what holds it#

“By eye” means the /design-audit skill’s look over every game’s screens (.claude/skills/design-audit/SKILL.md). A check kind in brackets is report-only for now: it’s printed, but doesn’t fail the run.

The checks, and what they measure#

How to run each one, and when, is in Testing and checks.

Every finding names its rule#

check:tokens, check:layout and check:details end each finding with the rule it breaks, by name, as [one-skeleton], so a finding leads straight to its principle (/guide/design/principles/#one-skeleton). The names come from tools/house/rulebook.mjs, which reads them from the Principles chapter’s headings, and a name that isn’t a rule throws:

// A finding's rule, by name, for a check's output: "[one-skeleton]". An
// unknown name throws, so a check can't cite a rule that isn't one.
export function rule(name) {
  if (!NAMES.has(name)) throw new Error(`no design rule named ${name} in ${PRINCIPLES}`);
  return `[${name}]`;
}

check:details maps each kind it finds to its rule:

// Each kind check:details finds, and the rule it holds.
export const DETAILS = {
  center: 'centered-by-ink', icon: 'centered-by-ink', overlap: 'nothing-over-anything',
  clip: 'words-fit', overflow: 'words-fit', offscreen: 'every-screen-fits', align: 'rows-in-line',
  tap: 'a-fingers-reach', taken: 'a-fingers-reach', stray: 'keys-and-focus',
  alike: 'look-follows-meaning', room: 'room-to-breathe', readable: 'readable',
};

Nothing goes unheld. tools/house/rulebook.test.mjs, part of npm run check:house, fails when:

• a rule in Principles is missing from the table above, or the table names one that isn’t a rule;
• a rule’s row has nothing in it: no kit, no check and not by eye;
• a kind check:details finds has no rule, or its rule’s row doesn’t list it (in brackets while it’s report-only);
• check:tokens or check:layout cites a rule that doesn’t exist.

So a new rule comes with what holds it, and renaming one means renaming it everywhere it’s cited.

Exceptions#

A finding that’s meant is listed with why, and every other finding is fixed. The lists are in the checks themselves:

• ALLOW in tools/house/details.mjs: a badge on a corner, a fanned hand under 44px, a seat’s name ellipsized, and the rest.
• EXCEPTIONS in tools/house/layout.mjs: The Register’s masthead, the one title not on the scale.

An exception names the screen and the reason a player would recognize. “The code put it there” isn’t a reason.