Saga: Explore layout contracts and constraint-aware CSS analysis

[lbliii]

Status

Incubation / not currently scheduled. This saga preserves a high-upside Kida direction for later selection; it does not authorize a general CSS engine or a public API yet.

Thesis

Kida could treat a rendered application as a compositional layout-constraint graph: base layout → component → nested component → slot/content. For a deliberately analyzable CSS subset, it could prove layout contracts over declared viewport, variant, and content ranges; when a contract fails, it should produce the smallest counterexample, the ancestor-to-descendant explanation path, and ranked repairs that preserve the stated priorities.

This is not “lint arbitrary CSS numbers.” The value is whole-tree, source-aware reasoning over Kida-owned templates, props, slots, branches, and styles.

User value

• Detect a provable failure before a browser run: fixed children, padding, gaps, borders, and track sizes cannot fit their available space.
• Explain ownership: show the layout path that establishes available space and the child requirement that conflicts with it.
• Cover cases screenshot tests commonly miss: an exact unsafe viewport interval, an optional badge/slot branch, a longer localized string, or a token change.
• Eventually recommend the smallest token-aware adjustment that satisfies authored layout priorities.

Example desired diagnostic:

KCSS014: ProductCard title row cannot fit at 375px.

Available:
  AppShell 375px → MainLayout gutters 24px → ProductGrid 2 columns / 12px gap
  → card 157.5px → card padding 32px = 125.5px

Required:
  badge 64px + gap 8px + title min-content 72px = 144px

Conflict: required width exceeds available width by 18.5px.

Product principles

1. Opt-in contracts; bare HTML/CSS remains first-class. Zero-config checks may flag only obvious, proven errors. Stronger guarantees require a local layout contract.
2. Honest certainty. Diagnostics classify results as proved failure, possible risk, or outside the analyzable subset.
3. Explain before suggesting. Every result carries source locations and a constraint/ownership trace.
4. No browser-engine cosplay. Kida analyzes a useful subset, then optionally asks a real browser to validate dynamic or external boundaries.
5. Priorities make “ideal” meaningful. Any auto mode optimizes declared goals—e.g. preserve touch targets and wrapping, prefer tokens, minimize breakpoints and overrides—not an ungrounded aesthetic score.
6. No surprise mutations. Recommendations are reviewable patches. Applying fixes automatically is a distant, explicitly enabled stage.

Proposed staged plan

• 0. Product and technical discovery

  • Define a small layout-contract syntax or metadata shape without committing it as public API.
  • Inventory Kida template/style ownership and identify the minimum pipeline slice: source form, parser/node shape where needed, analysis/compiler integration, diagnostics, and reached render surfaces.
  • Establish benchmark corpus: simple flex/grid fits, nested components, optional slots, token changes, responsive boundaries, text/content bounds, and intentional unsupported cases.
  • Write success metrics: precision of proved failures, diagnostic comprehensibility, analysis latency, and annotation burden.

• 1. Private feasibility spike

  • Build a non-public prototype for literal lengths, design tokens/custom properties, calc(), box-model arithmetic, and a constrained flex/grid subset.
  • Construct a component/layout graph from Kida-owned render structure.
  • Emit a single overflow proof with a minimal counterexample and parent-to-child provenance.
  • Go/no-go: continue only if the prototype finds seeded regressions with clear explanations and no meaningful false-positive pattern.

• 2. MVP: layout contracts

  • Design an opt-in, stable contract for viewport/container range, relevant variant/slot states, content bounds, and invariants such as no overflow, minimum touch target, or line/wrap budget.
  • Add stable diagnostic codes, source locations, structured diagnostics, and actionable suggestions.
  • Verify semantic parity across every reached sync/async/full/block/stream and HTML/terminal/markdown/report surface, recording intentional surface differences.
  • Publish docs, examples, schema/scaffold collateral as applicable, and the required downstream-pilot classification.

• 3. Responsive and browser validation

  • Symbolically find risk/failure intervals within a declared viewport range.
  • Add an optional browser-backed confirmation path for fonts, intrinsic sizing, dynamic CSS, and third-party-layout boundaries.
  • Keep sampled browser results distinct from static proof in diagnostics and CI reports.

• 4. Recommendations, then constrained auto mode

  • Generate ranked, token-aware candidate patches (spacing, padding, track sizing, wrapping, breakpoints).
  • Require explicit optimization priorities and show all trade-offs.
  • Consider auto-apply only for a narrowly safe, reversible patch class after recommendation quality is proven.

Explicit non-goals for the MVP

• Full CSS specification or browser-layout-engine reimplementation.
• Guarantees across arbitrary runtime DOM mutations, unbounded user content, or unmodeled third-party CSS.
• A global mandate to use Kida layout primitives or rigid component libraries.
• “Beauty” scoring without authored design intent.
• Silent CSS rewrites.

Key technical and product risks

• CSS scope explosion: cap the supported subset and surface unsupported constructs clearly.
• Annotation friction: infer literal/token facts; ask authors only for information unavailable from source, especially content and priority bounds.
• False certainty: preserve the proof/risk/unknown distinction, and use browser confirmation for the dynamic remainder.
• Performance: measure analysis time on realistic component trees from the first spike.
• Public-contract blast radius: do not expose syntax, API, or stable diagnostic codes until the spike validates the model.

Evidence and prior art

• Solver-aided layout reasoning: Cassius.
• Formal assertions for web geometry/accessibility/usability across layouts: Visual Logic.
• Runtime responsive-failure detection: ReDeCheck.
• Automated responsive-layout repair research: Althomali et al..
• Design-side nested responsive constraints: Figma Auto Layout.

Initial decision gate

Pick up Phase 0 only when we can fund a bounded research spike. Promote it to product work only if Phase 1 demonstrates:

• at least one compelling, whole-tree failure explanation that ordinary CSS linting and screenshots do not provide;
• useful accuracy on the seeded corpus;
• a local authoring model with low annotation burden; and
• a credible path that preserves Kida’s zero-runtime-dependency contract.

Steward Notes

• Consulted: root constitution; GitHub workflow steward.
• Risks: static-analysis and compiler boundaries, diagnostics/public-contract implications, multi-surface parity, performance, and downstream-observable feature scope.
• Evidence: prior-art links above and the planned seeded corpus.
• Collateral: no code, schema, docs, examples, or release collateral changes in this saga; required only if a later phase is accepted.
• Downstream pilot: No downstream pilot — planning-only proposal with no externally observable implementation or contract change.
• Unresolved trade-offs: whether contracts are template syntax, external metadata, or Python API; whether browser validation belongs in Kida core or an optional contrib/CI adapter.