A centralized, developer-accessible design system documentation platform that makes design guidance available directly within coding environments through AI assistants and other tools.

This open-source repository serves as the single source of truth for our design system documentation, organized in a way that's both human-readable and machine-accessible through Model Context Protocol (MCP) servers. Our goal is to bridge the gap between design guidance and development implementation, ensuring design system resources are accessible exactly when and where they're needed most.

Visit our live documentation site to explore the design system.

We welcome contributions! Please read our Contributing Guide to get started.

• Python 3.8+
• Git

# Clone the repository
git clone [https://github.com/appian-design/aurora.git](https://github.com/appian-design/aurora.git)
cd design-system-docs

# Create and activate a virtual environment
# On macOS/Linux:
python3 -m venv venv
source venv/bin/activate

# On Windows:
python -m venv venv
.\venv\Scripts\activate

# Install mkdocs material 
pip install mkdocs-material

# Start the live-reloading server
mkdocs serve

# View the site in your browser at [http://127.0.0.1:8000](http://127.0.0.1:8000)

Any changes you save will automatically reload in the browser.

This design system documentation includes:

• Components: Individual UI components with usage guidelines and code examples
• Patterns: Reusable design patterns for common interface problems
• Layouts: Page-level layout templates and structural guidance
• Branding: Core brand identity elements including colors, typography, and iconography
• Accessibility: Comprehensive guidelines and checklists for inclusive design
• Content Style Guide: Guidelines for voice, tone, and content consistency

aurora/
├── .github/              # GitHub automation and workflows
│   ├── workflows/        # GitHub Actions for deployment and sync checking
│   └── scripts/          # Automation scripts for MCP server sync
├── docs/                 # Contains all Markdown documentation files
│   ├── index.md          # The home page
│   ├── assets/           # Images, CSS, or JS overrides
│   └── ...               # Subdirectories for components, patterns, etc.
├── mkdocs.yml            # MkDocs configuration file
├── requirements.txt      # Python dependencies for local development
└── README.md             # This file

We believe that great design systems are built by communities. Whether you're a designer, developer, content creator, or accessibility expert, there are many ways to contribute:

• Report Issues: Found a bug or have a suggestion? Open an issue
• Improve Documentation: Help us make our docs clearer and more comprehensive
• Add Examples: Contribute code examples and implementation guides
• Enhance Accessibility: Help us make our design system more inclusive
• Share Patterns: Document new design patterns you've discovered

1. Edit directly in GitHub: Use GitHub's web interface to edit markdown files
2. Create a branch: Always work on a feature branch for changes
3. Request review: Open a pull request when ready for feedback
4. Collaborate: Use PR comments for discussion and iteration

1. Fork the repository: Click the "Fork" button on GitHub
2. Clone your fork: git clone https://github.com/YOUR-USERNAME/design-system-docs.git
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make changes: Edit markdown files or add new documentation
5. Test locally: Run mkdocs serve to preview changes
6. Submit PR: Push changes and open a pull request for review

Please read our Contributing Guide for detailed information and our Code of Conduct for community guidelines.

This repository is designed to work with the Aurora MCP Server that makes documentation available directly within AI coding assistants. Changes made here are automatically synchronized with the MCP server through automated workflows, enabling:

• Real-time access to design system guidance within development environments
• AI-powered assistance with component selection and implementation
• Contextual design recommendations during coding

For AI assistants working with this repository, see AGENTS.md for guidance on documentation structure, formatting conventions, and best practices.

All documentation files use Markdown with YAML front matter:

---
status: "stable"
last_updated: "YYYY-MM-DD"
parent: "category-name"
related: ["related-item-1", "related-item-2"]
---

# Title

## Design

### Subsection

### Accessibility

## Development

### Sample 1

    ```html
    <code>
    ```

### Sample 2

    ```html
    <code>
    ```

• GitHub Pages: Static documentation site automatically deployed from main branch
• MCP Server: Documentation metadata automatically synchronized with the Aurora MCP Server for AI integration

• GitHub-flavored Markdown reference
• markdownTables: for converting HTML table content to Markdown tables
• mkdocs Material Documentation
• Accessibility Guidelines

• Documentation: Check our existing documentation first
• Issues: Search existing issues before creating new ones
• Discussions: Start a discussion for questions and ideas
• Contributing: Read our Contributing Guide for detailed guidance

See the LICENSE file for details.

This project builds upon the collective wisdom of the Appian UX Design Team and larger design community. We're grateful for the open-source tools, patterns, and practices that make this work possible. And also the LLMs.

Made with ❤️ by the Appian UX Design Team