Support & Contributing

The Design System team provides support for adopters and welcomes contributions from product teams across the organization. This page explains how to get help, report issues, request features, and contribute to the system.

Getting Help

Before reaching out, we recommend consulting these resources:

Search this documentation — Many common questions have been addressed in our component or guides docs pages.
Check our GitHub Issues — Someone may have encountered the same problem.

Support Channels

Channel	Purpose	Response Time
#designsystem	General discussions & announcements	Same business day
GitHub Discussions	Technical Q&A, RFCs, & suggestions	1-2 business days
GitHub Issues	Bug reports, feature requests	1-2 business days

Reporting Issues

Found a bug in the Design System? Follow these steps to report it effectively.

Before You Report

Verify it’s a DS issue — Ensure the bug is in a Design System package, and not your application code.
Check existing DS issues — Search GitHub Issues to avoid duplicates.
Reproduce the issue — Confirm you can reproduce the problem. If we cannot determine the issue is reproducible, we may close the issue as per our Governance Model.

Submit Your Report

Open a Bug Report — Use the Bug Report form to file your issue
Complete the template — Fill out all required fields.

⚠️ Issues with insufficient information may be closed
Track the report — The #designsystem team will be notified and triage the report. A team member will reach out if additional information is needed

Requesting Features

Have an idea for improving the Design System? We’d love to hear it.

Before You Request

Check if it already exists — Search our documentation and Storybook thoroughly to see if the feature is already available. It may be actively in beta or experimental state.
Search existing requests — Look through GitHub Issues to avoid duplicate requests.
Consider system fit — Review our component proposal criteria below to determine if it belongs in the Design System.
Understand the process — Features are evaluated according to our Governance Model for reusability, brand alignment, and maintenance impact.

Submit Your Request

Open a Feature Request — Use the Feature Request form to submit your idea.
Provide detail — Complete the template with as much context and justification as possible.
Follow the request — The DS team will review the request and triage within 2 business days.

Contributing Code

We welcome code contributions from our adopter community. Here’s how to contribute effectively.

Before You Start

Check for existing work — Search issues and PRs to avoid duplication.
Discuss first — For significant changes, open an issue or discuss in Slack before coding.
Read contribution guidelines — Review our CONTRIBUTING.md guide for more detailed instructions.

Component Proposal Criteria

New components go through evaluation before acceptance into the Design System.

Evaluation Criteria

Criterion	Description	Note
Reusability	Would multiple products use this?	2 team minimum
Compliance	Does it fit within CFA brand and voice guidelines?	Chick-fil-A® Brand Standards
Accessibility	Would it meet WCAG 2.1 AA requirements?	ADA regulatory baseline
Complexity	Is it appropriate and/or scalable within a shared design system?
Maintenance	Can the DS team maintain it long-term?

Code Review Process

All contributions go through automated and manual code review to maintain quality and project maintainability.

Review Check Summary

Security — Does this contribution introduce any vulnerabilities or sensitive data?
Correctness — Does it use appropriate abstractions (e.g. design tokens, primitives)?
Code quality — Is it maintainable, well-structured, and architecturally consistent?
Testing — Are there sufficient unit and visual tests?
Accessibility — Does it meet WCAG 2.1 AA accessibility threshold?
Documentation — Is it properly documented?
Performance — Are there any performance concerns in the current implementation?

System Entity Lifecycle

System components and patterns progress through defined maturity stages. The Governance Model is the canonical reference for lifecycle definitions, graduation criteria, and deprecation policy.

Stage	Decorator	What to Expect
🧪 Experimental	`UNSTABLE_`	May change or be removed without notice
🚧 Beta	None	API stabilizing, Storybook examples available
✅ Stable	None	Production-ready with full docs and guidelines
⚠️ Deprecated	`@deprecated`	Supported for 2+ major versions, then removed

Key Graduation Milestones

Experimental 🧪 → Beta 🚧 — API validated, tests in place, 1 team piloting
Beta 🚧 → Stable ✅ — A11y audit passed, docs complete, Figma aligned, 2+ teams using
Stable ✅ → Deprecated ⚠️ — Replacement identified, migration guide provided, announced in changelogs

For full graduation criteria and the deprecation process, see Graduation Criteria and Breaking Changes & Deprecation Policy in the Governance Model.

Decision & Delivery Flow

The following diagram shows how features and changes flow through the Design System governance process. This helps teams understand when to engage the DS team and what to expect at each stage.

flowchart TD
  %% =========================
  %% ENTRY
  %% =========================
  A([Start: Product Need Identified])

  %% =========================
  %% EXISTING FEATURE CHECK
  %% =========================
  B{Does the feature exist?}
  C{Does it fulfill all requirements?}
  DONE1([Good to go!])
  D[Has there been a conversation with DS team?]
  E[If necessary, DS updates docs to close gaps]
  F{Are system changes or new development needed?}

  A --> B
  B -->|Yes| C
  C -->|Yes| DONE1
  C -->|No| D
  B -->|No| D
  D --> E --> F

  %% =========================
  %% NO NEW WORK PATH
  %% =========================
  G[Recipes / Snowflakes]
  G1{Valid product-specific component or recipe?}
  G2[Product team adds to product backlog]
  G3[Product team decides if they want to build]
  G4[DS team adds to DS backlog]

  F -->|No| G --> G1
  G1 -->|Yes| G2
  G1 -->|No| G3

  %% =========================
  %% YES - NEW WORK
  %% =========================
  H{Nature of the change?}

  F -->|Yes| H

  %% NEW FEATURE PATH
  I{Should the new feature belong in the DS?}
  J{Does the DS team have capacity to deliver at quality?}
  K[New / Updated DS Component or Variant]

  H -->|New feature| I
  I -->|No| G
  I -->|Yes| J
  J -->|No| G4
  J -->|Yes| K

  %% VISUAL DISCREPANCY PATH
  V1{Discrepancy between DS Figma and DS code?}
  V2{Discrepancy deliberate and justifiable?}
  V3[Product updates design to align to DS conventions]
  V4[Product implements custom design]
  V5[DS adds issue to backlog]
  V6[DS follows up with product team]
  V7[Findings captured for research if needed]

  H -->|Visual discrepancy| V1
  V1 -->|No product-level| V2
  V2 -->|No| V3
  V2 -->|Yes| V4
  V1 -->|Yes DS inconsistency| V5 --> V6 --> V7 --> K

  %% BUG PATH
  Bug1{Issue in existing DS design or code?}
  BUG1[Bug added to backlog High Priority]
  BUG2[DS follows up with adopter]

  H -->|Bug| Bug1
  Bug1 -->|Yes| BUG1 --> K
  Bug1 -->|No| BUG2

  %% =========================
  %% FORMAL DS PROCESS
  %% =========================
  P1[DS reviews issue]
  P2[Create feature branch in Figma]
  P3[Create feature branch in codebase]
  COLLAB[Build / design collaboratively]

  K --> P1
  P1 --> P2 --> COLLAB
  P1 --> P3 --> COLLAB

  %% =========================
  %% QUALITY, REVIEW, RELEASE
  %% =========================
  QA1[Validate functionality, content, a11y, etc.]
  QA2[Testing unit, visual regression, UAT]
  REV1[Review code, design, product]
  REV2[Feature demo if needed]

  PR1{Does product team approve?}
  ITERATE1[Iterate]
  DOCUMENT1{Is documentation needed?}
  DOCUMENT2[Add documentation]

  REL1[Bump versions per semver guidelines]
  REL2[Add release notes / changelog]
  REL3{Does it work as expected?}
  REL4([Ship new DS release])
  REL5[Announce release in Slack channels]

  COLLAB --> QA1 --> QA2 --> REV1 --> REV2 --> PR1
  PR1 -->|No| ITERATE1 --> PR1
  PR1 -->|Yes| DOCUMENT1
  DOCUMENT1 -->|Yes| DOCUMENT2 --> REL1
  DOCUMENT1 -->|No| REL1

  REL1 --> REL2 --> REL3
  REL3 -->|Yes| REL4 --> REL5
  REL3 -->|No| ITERATE1

  %% =========================
  %% PRODUCT ADOPTION
  %% =========================
  ADOPT1{Able to test new feature?}
  ADOPT2[Wire component into application]
  ADOPT3[Test in application]
  ADOPT4{Works as expected?}
  ADOPT5([Adoption complete!])
  ADOPT6[Report issue to DS team]

  REL4 --> ADOPT1
  ADOPT1 -->|Yes| ADOPT2 --> ADOPT3 --> ADOPT4
  ADOPT1 -->|No| ADOPT6
  ADOPT4 -->|Yes| ADOPT5
  ADOPT4 -->|No| ADOPT6
  ADOPT6 --> H

  %% =========================
  %% VISUAL GROUPING
  %% =========================
  subgraph S0[Entry and Triage]
    A
    B
    C
    D
    E
    F
    DONE1
  end

  subgraph S1[No New Work: Recipes / Snowflakes]
    G
    G1
    G2
    G3
  end

  subgraph S2[New Work: Classification]
    H
    I
    J
    V1
    V2
    V3
    V4
    V5
    V6
    V7
    Bug1
    BUG1
    BUG2
    G4
  end

  subgraph S3[Design System Delivery]
    K
    P1
    P2
    P3
    COLLAB
    QA1
    QA2
    REV1
    REV2
    PR1
    ITERATE1
    DOCUMENT1
    DOCUMENT2
    REL1
    REL2
    REL3
    REL4
    REL5
  end

  subgraph S4[Adoption]
    ADOPT1
    ADOPT2
    ADOPT3
    ADOPT4
    ADOPT5
    ADOPT6
  end

  %% =========================
  %% STYLING
  %% =========================
  classDef start fill:#ffedec,stroke:#dd0033,stroke-width:2px,rx:10,ry:10,color:#2f3b43;
  classDef done fill:#e6f2ed,stroke:#077e4c,stroke-width:2px,rx:10,ry:10,color:#2f3b43;
  classDef decision fill:#fff9e7,stroke:#fbc111,stroke-width:2px,color:#2f3b43;
  classDef backlog fill:#f0f1f1,stroke:#5b6770,stroke-dasharray: 4 3,color:#2f3b43;
  classDef ds fill:#e5f2ff,stroke:#004f71,color:#2f3b43;
  classDef product fill:#ffecf3,stroke:#994878,color:#2f3b43;
  classDef release fill:#e6f0f5,stroke:#006b9a,stroke-width:2px,rx:10,ry:10,color:#2f3b43;

  class A start
  class DONE1,ADOPT5 done
  class B,C,F,H,I,J,V1,V2,Bug1,PR1,DOCUMENT1,REL3,ADOPT1,ADOPT4 decision
  class G2,G4,BUG1,V5 backlog
  class K,P1,P2,P3,COLLAB,QA1,QA2,REV1,REV2,DOCUMENT2,REL1,REL2 ds
  class V3,V4,G3,BUG2,ADOPT2,ADOPT3,ADOPT6 product
  class REL4 release

CONTRIBUTING.md — Detailed contribution guidelines
GOVERNANCE.md — Full governance model and decision-making and delivery flow
CODEOWNERS — Who reviews what and responsible for final decision making