Skip to content

Add optional annotations tab to ORCA design reference#129

Open
mryhmln wants to merge 2 commits intomainfrom
feat/128-design-reference-annotations
Open

Add optional annotations tab to ORCA design reference#129
mryhmln wants to merge 2 commits intomainfrom
feat/128-design-reference-annotations

Conversation

@mryhmln
Copy link
Copy Markdown
Collaborator

@mryhmln mryhmln commented Mar 2, 2026

Summary

  • Add --annotations=<dir> flag to export-design-reference.js that loads field-level annotation YAML files
  • Render an "Annotations" tab per schema with a program requirement matrix, source badges (system, applicant, derived, etc.), and expandable statute/notes details
  • Feature is fully opt-in — without the flag, output is unchanged
  • Remove unused global state selector UI (sidebar buttons, CSS, JS)
  • Update ORCA intro to clarify OOUX/ORCA methodology
  • Default active tab to "attributes" instead of "overview"
  • Add unknown-argument rejection for the --annotations flag

Closes #128

How to validate

  1. Check out the branch and install:

    git checkout feat/128-design-reference-annotations && npm install
    
  2. Verify the script still works without annotations (no behavior change):

    node packages/contracts/scripts/export-design-reference.js \
      --spec=packages/contracts --out=/tmp/ref-test
    

    Open /tmp/ref-test/schema-reference.html — should render normally with no Annotations tab.

  3. Verify annotations load when provided (create a test annotation file):

    mkdir -p /tmp/test-annotations
    cat > /tmp/test-annotations/application.yaml << 'YAML'
    schema: applications/Application
    fields:
      status:
        source: system
        programs:
          SNAP: required
          TANF: required
        statute: "7 CFR 273.2"
        notes: "Set automatically on submission"
    YAML
    
    node packages/contracts/scripts/export-design-reference.js \
      --spec=packages/contracts --out=/tmp/ref-test \
      --annotations=/tmp/test-annotations
    

    Open /tmp/ref-test/schema-reference.html, navigate to Application, and confirm the Annotations tab appears with the source badge and program matrix.

  4. Run preflight:

    npm run preflight
    

mryhmln added 2 commits March 2, 2026 15:04
- Add --annotations=<dir> flag to load field-level annotation YAML files
- Render program requirement matrix with source badges and statute details
- Remove unused global state selector UI (sidebar buttons, CSS, JS)
- Update ORCA intro description and default to attributes tab
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add optional annotations tab to ORCA design reference

1 participant