TenantAtlas/specs/200-filament-surface-rules/research.md

Research: UI/UX Constitution Extension: Filament Nativity & Custom Surface Rules

Decision 1: Amend existing constitution sections instead of creating a parallel UI rulebook

• Decision: Integrate Spec 200 into the existing constitution sections UI-SURF-001, ACTSURF-001, UI-HARD-001, UI-EX-001, Filament UI — Action Surface Contract, and UX-001.
• Rationale: The repo already has a binding UI constitution. Extending those sections keeps one authority path for surface taxonomy, action discipline, hard rules, exceptions, Filament-specific contracts, and layout or IA guidance. This directly satisfies the spec's requirement to avoid a parallel rule hierarchy.
• Alternatives considered:
  • Create a new top-level “Filament Nativity Constitution” section: rejected because it would force reviewers to reconcile two overlapping rulebooks.
  • Keep the rules distributed only across Specs 196 through 199: rejected because reviewers still need one durable product-language source rather than four adjacent historical specs.

Decision 2: Treat native-by-default and fake-native as explicit extensions of existing UI-FIL-001 and UI-HARD-001 behavior

• Decision: Add an explicit native-by-default rule and a named fake-native anti-pattern to the existing Filament-native and hard-rule sections instead of inventing new standalone IDs.
• Rationale: UI-FIL-001 already says native Filament components come first, but it does not yet give reviewers a sharp fake-native vocabulary or clearly outlaw GET-form/request-driven body state for standard interactions. Spec 196 proved that gap.
• Alternatives considered:
  • Leave native-by-default implicit in existing Filament guidance: rejected because implicit guidance did not prevent the repo's fake-native drift cases.
  • Introduce a new UI-FIL-NATIVE-001 rule ID: rejected because the problem belongs inside the existing Filament-native section and hard-rule family.

Decision 3: Model shared detail micro-UI and host variation as an extension of the current action-surface and exception framework

• Decision: Add shared-family and host-variation rules beneath the existing Filament UI contract and exception model instead of describing them as an unrelated custom-UI system.
• Rationale: Spec 197 proved that the repeated problem is not “custom UI is bad,” but that repeated detail surfaces need one shared contract before host-specific variation is allowed. The existing action-surface and exception sections already govern how surfaces, actions, and deviations are classified.
• Alternatives considered:
  • Create a separate “shared micro-UI framework” document: rejected because it would overproduce structure for two proven families and separate the rule from the main constitution.
  • Treat each host difference as a local PR concern: rejected because that is what allowed host drift to accumulate in the first place.

Decision 4: Reuse the state-language proven in Specs 198 and 199 rather than invent a new runtime state taxonomy

• Decision: Carry forward shell/page/detail ownership and requested/active/draft/inspect/restorable distinctions as constitution vocabulary only, with no new runtime state framework in this spec.
• Rationale: Specs 198 and 199 already proved the important state distinctions. Spec 200's job is to make those distinctions reviewable across future UI work, not to create a new implementation layer.
• Alternatives considered:
  • Invent a fresh cross-product state taxonomy here: rejected because the repo already has adjacent specs proving the needed terms.
  • Limit the spec to visual nativity only: rejected because state-layer collapse is one of the core drift classes this spec must cover.

Decision 5: Extend the existing exception model instead of normalizing hidden exceptions

• Decision: Keep UI-EX-001 as the home for bounded exceptions and extend it with Spec 200's legitimate custom-surface and host-variation needs.
• Rationale: The repo already recognizes that exceptions must be named, justified, and tested. Spec 200 broadens that discipline to fake-native escapes, legitimate custom surfaces, shared-family host variation, and state-related special cases without weakening the existing exception posture.
• Alternatives considered:
  • Let individual specs define their own exception vocabulary: rejected because that recreates local drift.
  • Ban all custom surfaces to avoid exceptions entirely: rejected because the product legitimately includes richer diagnostic, review, and visualization surfaces.

Decision 6: Treat the contracts artifact as an explicit no-runtime governance contract

• Decision: Create a docs-only contract note under contracts/ that records amendment targets, acceptance conditions, and deferrals instead of inventing REST or GraphQL endpoints.
• Rationale: Spec 200 introduces no user-facing API, route, or transport contract. The contract surface is the constitution amendment itself, so the artifact should make that boundary explicit rather than fabricate runtime endpoints that the spec forbids.
• Alternatives considered:
  • Create a fake OpenAPI file: rejected because it would imply runtime behavior the feature does not add.
  • Omit contracts/ entirely: rejected because the planning workflow expects an artifact and the no-runtime boundary should be made explicit.

Decision 7: Reference operator-UX standards for language and disclosure, but defer review-checklist operationalization to Spec 201

• Decision: Use docs/ui/operator-ux-surface-standards.md as the supporting operator-language and progressive-disclosure reference, but keep checklist-template and enforcement work out of Spec 200 unless a wording-only cross-reference becomes unavoidable.
• Rationale: Spec 200 is the rule and vocabulary slice. Spec 201 is the enforcement slice. That mirrors the repo's existing TEST-GOV-001 pattern, where standing governance rules live in the constitution and later specs operationalize them in templates and CI.
• Alternatives considered:
  • Update review checklists now: rejected because it would blur the line between constitution definition and enforcement.
  • Ignore operator-UX standards docs completely: rejected because the constitution language should remain aligned with the repo's normative operator-facing UI guidance.

Decision 8: Keep the implementation footprint intentionally small

• Decision: Plan for constitution changes in .specify/memory/constitution.md, feature-local artifacts in specs/200-filament-surface-rules/, and at most wording alignment in docs/ui/operator-ux-surface-standards.md.
• Rationale: This keeps the scope proportional to a docs-only governance feature and avoids importing template, CI, or application-code changes that the spec explicitly defers.
• Alternatives considered:
  • Widen the plan to include .specify/templates/checklist-template.md: rejected because template operationalization is enforcement work for Spec 201.
  • Widen the plan to include runtime examples in app/ or tests/: rejected because Spec 200 is not an implementation spec.

Decision 9: Put the new vocabulary into the existing rule families and appendices instead of creating a separate glossary section

• Decision: Introduce the new terms and anti-patterns inside the already binding rule families (UI-SURF-001, UI-HARD-001, UI-EX-001, UX-001, UI-REVIEW-001, UI-FIL-001) plus the condensed appendix/checklist/red-flag appendices, rather than creating a standalone vocabulary chapter.
• Rationale: Reviewers need the terms exactly where they classify behavior. A standalone glossary would recreate the split-rulebook problem this spec is supposed to remove.
• Alternatives considered:
  • Add a new glossary-only top-level constitution section: rejected because the review language would become detached from the operative rules.
  • Keep the vocabulary only in the Spec 200 artifact set: rejected because the constitution would still be missing the durable review language.

Decision 10: Review questions should absorb nativity, shared-family, and state-layer checks directly

• Decision: Expand UI-REVIEW-001, Appendix B, and Appendix C with the new classification and anti-pattern checks rather than invent a second reviewer rubric for Filament nativity or state ownership.
• Rationale: The existing enforcement model and appendices are already the review intake for operator-facing UI changes. Extending that surface is the narrowest way to make the new rules usable.
• Alternatives considered:
  • Create a dedicated nativity/state checklist: rejected because it would fragment one review routine into multiple parallel rubrics.
  • Leave the new language implicit and rely on reviewer judgment: rejected because that is the current failure mode.

Implementation Adjustment Note

• During implementation, the repo-level operator UX standards document only needs wording alignment that points back to the constitution vocabulary. A second standards track for native/custom/shared/state terminology would be overproduction and is intentionally avoided.