# The parts we can govern

A practical index of design decisions, from spacing and surfaces to controls, assets, and behavior, with one home for each category.

HTML page: https://developer.mpalo.com/elements
Markdown page: https://developer.mpalo.com/elements.md

## Navigate sections

- [Foundations](elements#foundations)
- [Components](elements#components)
- [Patterns and states](elements#patterns)
- [Assets and expression](elements#assets)
- [Ownership and evidence](elements#governance)

## Foundations set the available choices

Foundations are named decisions used by many interface parts. They should be defined once, versioned, and assigned to the domains that use them.

- **Identity and language**: Mission, principles, terminology, voice, capitalization, and claim rules. Answers what Mpalo means and how it speaks.

- **Color and surfaces**: Palette, semantic color roles, domain themes, contrast, surface hierarchy, and feedback colors. Answers how visual emphasis and state are communicated.

- **Typography**: Font families, roles, scale, weights, line lengths, and code styling. Answers how information expresses audience and hierarchy.

- **Layout and spacing**: Page structures, grids, width, alignment, responsive rules, spacing scale, gaps, margins, and padding. Answers where things go and how their relationships read.

- **Shape and depth**: Corner treatment, borders, separators, shadows, and layering. Use only when shape or depth communicates grouping, interaction, or state.

- **Icons and media**: Icons, photography, illustration, diagrams, video, animation, and Palo appearances. Answers what an asset communicates and what text equivalent accompanies it.

## Components solve repeated interface needs

A component is a reusable control or container with a defined purpose, visual states, behavior, and accessibility contract.

- **Actions**: Buttons, links, icon buttons, and menus. Define priority, keyboard behavior, focus, disabled state, and feedback.

- **Inputs and prompts**: Text fields, selectors, switches, dialogs, and prompt boxes. Define labels, instructions, validation, submission, and recovery.

- **Containers and cards**: Group related information or actions. Use surface contrast and spacing first; use borders or separators only where they improve structure.

- **Navigation and search**: Headers, sidebars, breadcrumbs, tables of contents, mobile menus, and search. Define current location, responsive behavior, and keyboard access.

- **Data display**: Tables, status labels, graphs, code blocks, and summaries. Define reading order, units, text equivalents, and uncertainty.

## Patterns describe complete tasks and states

Patterns combine components to help someone complete a task or understand a system response. They should be documented separately from the reusable parts they contain.

- Onboarding and progressive disclosure
- Sign-in, account recovery, and verification
- Validation errors and successful completion
- Loading, empty, unavailable, and permission states
- Confirmation, destructive actions, and undo or recovery
- Keyboard navigation, search, and responsive navigation
- Status and capability communication

## Assets carry meaning

Images, icons, video, animation, and Palo the cat should clarify identity or content. Record their source, rights, intended domain, alt-text approach, and any motion behavior.

Do not use an asset merely to fill space. If an asset has no clear communication role, leave it out. Motion respects reduced-motion preferences and never carries information by itself.

## Make each decision reviewable

Every catalog entry should answer the same questions so the system remains useful at Mpalo’s current scale.

1. **Purpose:** what user need or institutional requirement does it serve?
2. **Scope:** which domains use it, and which do not?
3. **Source:** which token, EJS/CSS module, component, or page currently implements it?
4. **Behavior:** what states, inputs, and recovery paths does it support?
5. **Evidence:** how was accessibility, responsive behavior, and implementation status checked?
6. **Lifecycle:** is it proposed, current, or retired, and who maintains it?

The catalog describes the intended system. It becomes a conformance source only when each entry has linked implementation evidence and a maintained check.

## Related pages

- [Principles that guide the work](principles.md)
- [One institution, distinct domains](domains.md)
- [How the pieces connect](map.md)

## Authoritative integration reference

- [API quickstart](https://api.mpalo.com/get-started)
- [API reference](https://api.mpalo.com/landing)