# Orbit (Orbit)

> Orbit is an accessibility-first, AI-optimised design system for Open Point's community and stakeholder engagement products. It serves government customers across Australia, New Zealand, Canada, the US, France, and the Philippines.

Orbit provides tokens, components, patterns, and guidelines for building consistent, accessible interfaces across Social Point and Open Point SRM. All documentation is written to be consumed directly by AI tools. Tokens follow semantic naming conventions (e.g. color-action-primary), component descriptions specify when to use and when not to use, and a compact machine-readable spec is available at public/specs/design.md.

## Get Started

- [Home](src/pages/index.astro): Orbit is Open Point's design system — accessibility-first, AI-optimised, and built for the people who make community engagement software.
- [About Orbit](src/pages/get-started/about.mdx): What Orbit is and why it exists — the design system unifying Open Point, Social Point, and Converlens, with accessibility built in at the token level and a structure AI tooling can build against directly.
- [Library files](src/pages/get-started/library-files.mdx): Where to find the current Open Point and Social Point design library files — Figma libraries and Storybook.
- [Component lifecycle](src/pages/get-started/component-lifecycle.mdx): The three-axis component status model — Figma, Storybook, and Docs — what each status means and how components move through it.
- [Component status](src/pages/get-started/component-status.astro): A single table of every component's Figma, Storybook, and documentation status — the primary reference for sprint planning and spotting what's blocking Phase 3.
- [Roadmap](src/pages/get-started/roadmap.astro): The 7-phase rollout for the Orbit — what has shipped, what's in progress, and what's coming.
- [Changelog](src/pages/get-started/changelog.astro): A reverse-chronological record of what has shipped in Orbit — new components, token changes, deprecations, and breaking changes.

## AI Layer

- [AI Layer](src/pages/ai-tools/index.mdx): How Orbit is built to be read and used by AI tools directly — the structural choices that make it machine-readable, and how to point your tools at it.

## Foundations

- [Foundations overview](src/pages/foundations/index.astro): The building blocks of Orbit — design tokens and the visual styles (colour, typography, spacing, radius) that every component is built on.
- [Design tokens](src/pages/foundations/tokens.astro): The Orbit token system — three-tier structure, naming conventions, and category reference.
- [All tokens](src/pages/foundations/tokens/all-tokens.astro): Every Orbit design token in one searchable, filterable table — primitive, semantic, and component tiers together.
- [Colour](src/pages/foundations/colour.astro): The Open Point colour system — nine ramps, contrast ratios, and accessibility guidance.
- [Typography](src/pages/foundations/typography.astro): The Orbit type system — Heading and Body styles, line height tokens, and accessibility guidance.
- [Spacing](src/pages/foundations/spacing.astro): The Orbit spacing scale — a base-4px system of named tokens for every spacing decision.
- [Radius](src/pages/foundations/radius.astro): Border radius tokens for the Orbit design system — four values covering tight UI through fully rounded pill shapes.

## Guidelines

- [Guidelines overview](src/pages/guidelines.astro): Cross-cutting quality guidance for designing and building in Orbit — accessibility, UX, and content.
- [Accessibility](src/pages/accessibility/index.astro): Accessibility foundations for the Orbit — colour and contrast, focus, motion, touch targets, reading order, alt text, and form accessibility.
- [UX Guidelines](src/pages/ux-guidelines.mdx): The layer above component selection — how components combine into flows, what states a screen needs, page-level accessibility, and content that fits the audience. Applies to all UX work in Orbit.

## Components

- [Components overview](src/pages/components/index.astro): The full Orbit component library — usage guidance, variants, token references, and accessibility notes for every component.
- [Accordion](src/pages/components/accordion.mdx): Groups related content into collapsible sections to reduce visual complexity. Use when page content can be meaningfully chunked into distinct sections. Don't use when all sections need to be visible simultaneously. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-accordion--docs)
- [Alert](src/pages/components/alert.mdx): Displays a contextual feedback message in response to a user action or system event. Use to communicate success, errors, warnings, or informational updates inline. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-alert--docs)
- [Avatar](src/pages/components/avatar.mdx): Displays a user's profile image, initials, or a fallback icon to represent a person or organisation. Use to identify users in lists, comments, assignments, and profile surfaces. Don't use as a decorative element — always pair with a name or accessible label. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=131-3917 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-avatar--docs)
- [Badge](src/pages/components/badge.mdx): A small label used to display statuses or short metadata values on UI elements. Use when you need to communicate a status or attribute at a glance. Don't use for numeric counts — use Pill instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=120-3128 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-badge--docs)
- [BadgePriority](src/pages/components/badge-priority.mdx): A small label with a leading icon used to indicate urgency or priority level. Use when users need to quickly identify how critical an item is. Don't use for general statuses — use Badge instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=120-3128 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-badge-priority--docs)
- [Button](src/pages/components/buttons/button.mdx): Triggers a single action or navigation event. Use the primary variant for the most important action in a context, secondary for supporting actions, and tertiary for low-emphasis actions. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=38-6 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-button--docs)
- [ButtonGroup](src/pages/components/buttons/button-group.mdx): Displays two or more related buttons as a single, visually joined control. Use for segmented controls, pagination, and view toggles — never to group actions of different severity. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=5294-10 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-button-group--docs)
- [CloseButton](src/pages/components/buttons/close-button.mdx): A small dismissal button displaying an × icon. Use to close or dismiss modals, alerts, drawers, or tags. Don't use for destructive or irreversible actions — use a labelled Button with Destructive intent instead.
- [IconButton](src/pages/components/buttons/icon-button.mdx): A compact button that displays a single icon with no text label. Use in toolbars, table rows, or space-constrained UI where the icon alone clearly communicates the action. Don't use when the action needs a label for clarity. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=5350-10210 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-icon-button--docs)
- [SplitButton](src/pages/components/buttons/split-button.mdx): A button combining a primary action with a dropdown for secondary options. Use when one action is clearly dominant but related alternatives are available. Don't use when actions are equally weighted — use ButtonGroup instead.
- [Sticky Button](src/pages/components/buttons/sticky-button.mdx): A button that remains fixed in the viewport as the user scrolls. Use for persistent primary actions that must remain accessible throughout a long page or form. Don't use more than one Sticky Button per view.
- [Toggle Button](src/pages/components/buttons/toggle-button.mdx): A button that switches between two states such as active and inactive. Use for immediate, reversible binary actions that do not require form submission. Don't use when the toggle controls a persistent system setting.
- [Toggle View](src/pages/components/buttons/toggle-view.mdx): A button that switches between two views, such as list and thumbnail. Use for immediate, reversible view toggles that do not require form submission. Don't use when the toggle controls a persistent system setting.
- [TooltipButton](src/pages/components/buttons/tooltip-button.mdx): A small circular icon button that triggers a tooltip with contextual help text. Use next to form fields, settings, or UI elements that benefit from an inline explanation. Don't use for primary or secondary actions.
- [Containers](src/pages/components/containers.mdx): Structural layout components used to group and space related content. Use to establish visual hierarchy and contain distinct page regions. Don't use as a substitute for spacing tokens.
- [Data Display](src/pages/components/data-display.mdx): Renders structured or aggregated data in a formatted, readable layout for dashboards or reports. Use when data needs to be presented clearly for scanning or analysis. Don't use for simple key-value pairs.
- [Checkbox](src/pages/components/forms/checkbox.mdx): A small box that users can tick or untick to select or deselect an option. Use when users can pick more than one item from a list. Don't use when only one choice is allowed — use Radio Button instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=206-12385 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-checkbox--docs)
- [Colour Picker](src/pages/components/forms/colour-picker.mdx): Allows users to select or specify a colour via a visual picker or hex input. Use in configuration panels where a colour value is a required user input. Don't use when colours should be constrained to a token-defined palette. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=478-1836 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-color-picker--docs)
- [Date and Time Picker](src/pages/components/forms/date-time-picker.mdx): Allows users to select a date, time, or combined date-time value from a structured input. Use in forms wherever a precise date or time value is required. Don't use for simple date-only input where time is irrelevant.
- [Dropdown](src/pages/components/forms/dropdown.mdx): Allows users to select a single option from a collapsed list. Use in forms where there are more options than a radio group can display comfortably. Don't use when multiple selections are needed — use Multi-Select instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=469-3048 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-dropdown--docs)
- [File Upload](src/pages/components/forms/file-upload.mdx): Enables users to attach one or more files from their device via drag-and-drop or browse. Use in forms or workflows that require document or media attachment. Don't use without specifying accepted file types and size limits in the helper text.
- [Form Control](src/pages/components/forms/form-control.mdx): A wrapper that provides consistent label, helper text, and error messaging for form fields. Use to ensure all form inputs meet layout and accessibility standards. Don't apply custom label or error patterns outside this component. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-formcontrol--docs)
- [Input](src/pages/components/forms/input.mdx): A single-line text field for capturing freeform user input. Use for short, structured values like names, emails, and search queries. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=153-3160 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-input--docs)
- [Matrix](src/pages/components/forms/matrix.mdx): A survey question type presenting multiple statements as rows with a shared set of radio button response options across columns. Use in engagement surveys where participants rate several related statements using the same scale.
- [Multi-Select](src/pages/components/forms/multi-select.mdx): Allows users to select multiple options from a searchable dropdown list, displaying selections as removable tags. Use when a checkbox group would be too long or when options need to be searchable. Don't use when only one selection is allowed. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-multi-select--docs)
- [Radio Button](src/pages/components/forms/radio-button.mdx): Allows selection of exactly one option from a set of mutually exclusive choices. Use when options are few enough to display simultaneously and the user must choose only one. Don't use for binary on/off settings. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=206-6618 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-radio-button--docs)
- [Range Slider](src/pages/components/forms/range-slider.mdx): Allows users to select a numeric value or range by dragging a handle along a track. Use for bounded numeric input where approximate values are acceptable. Don't use when an exact value is required — use Input instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=213-6985 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-range-slider--docs)
- [Ranking](src/pages/components/forms/ranking.mdx): Allows users to order a list of items by preference or priority via drag interaction. Use in survey or consultation contexts where relative ordering is the required input. Don't use for lists longer than 7–10 items.
- [Rich Text Editor](src/pages/components/forms/rich-text-editor.mdx): A WYSIWYG editor supporting text formatting such as bold, lists, and hyperlinks. Use when users need to author structured or styled content within the product. Don't use for plain text form fields — use Input or Text Area instead.
- [Search](src/pages/components/forms/search.mdx): A text input that lets users search or filter content, with live suggestions as they type. Use for any search or filter interaction across the product. Don't use a standard Input field for search interactions. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-search--docs)
- [Selector](src/pages/components/forms/selector.mdx): Allows users to choose from a set of options presented as selectable cards or tiles. Use when options benefit from richer visual presentation than a radio button or dropdown provides. Don't use when there are more than 6–8 options.
- [Switch](src/pages/components/forms/switch.mdx): A toggle control for enabling or disabling a binary setting with immediate effect. Use in settings panels and preference controls where the change applies without form submission. Don't use when the action needs a confirmation step. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=210-6596 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-switch--docs)
- [Text Area](src/pages/components/forms/text-area.mdx): A multi-line text input for capturing longer freeform content. Use when the expected input exceeds a single line. Don't use for structured or formatted content — use Rich Text Editor instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=165-5027 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-text-area--docs)
- [Loading Status](src/pages/components/loading-status.mdx): Indicates that content or a process is in a loading or pending state. Use spinners for small inline states and skeleton variants for larger content areas. Don't use a spinner for a process with a known completion percentage.
- [Modal](src/pages/components/modal.mdx): A dialog overlay that focuses user attention on a task or decision. Use when an action requires explicit user confirmation. Don't use for non-critical information that can be shown inline — use Alert instead. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-modal--docs)
- [Notification Modal](src/pages/components/notification-modal.mdx): A modal variant used to surface system-level notifications that require user acknowledgement. Use for high-priority messages that must interrupt the user's current flow. Don't use for routine feedback — use Alert instead. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-notification-modal--docs)
- [Pagination](src/pages/components/pagination.mdx): Allows users to navigate through large data sets split across multiple pages. Use when a list or table contains more items than can be shown in a single view. Don't use for continuous scroll interfaces. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=5326-11389 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-pagination--docs)
- [Pill](src/pages/components/pill.mdx): A small label used to display a count or numeric value, typically attached to another component. Use when you need to show a quantity at a glance. Don't use for status labels or categories — use Badge instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=120-3128 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-pill--docs)
- [Placeholders](src/pages/components/placeholders.mdx): Empty state components displayed when no content is available in a view. Use to guide users toward a relevant action when a list, table, or page has no data. Don't leave empty states blank.
- [Progress Stepper](src/pages/components/progress-stepper.mdx): Displays a user's current position within a multi-step process. Use in wizards or guided workflows to communicate progress. Don't use for processes with more than 7 steps. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-progress-stepper--docs)
- [Sentiment](src/pages/components/sentiment.mdx): Captures a qualitative user response using icons or scale indicators such as star ratings or emoji reactions. Use in feedback or survey flows where a structured emotional or satisfaction response is needed. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-sentiment--docs)
- [Spinner](src/pages/components/spinner.mdx): Indicates that a process is loading or in progress. Use for small or inline loading states. Don't use for large content areas — use a skeleton loader pattern instead. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-spinner--docs)
- [Stepper](src/pages/components/stepper.mdx): A stepped navigation component used to guide users through a sequential multi-stage process. Use when each step must be completed in order. Don't use for more than 7 steps. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-stepper--docs)
- [Surfaces](src/pages/components/surfaces.mdx): The background/elevation treatment everything else in the system sits on top of. Use to establish depth and visual hierarchy between page background, cards, and floating content. Don't use as a substitute for spacing or container tokens.
- [Table](src/pages/components/table.mdx): Displays structured data in rows and columns with support for sorting, pagination, and row selection. Use for dense data sets that require comparison or scanning. Don't use for simple key-value data. (Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-table--docs)
- [Tabs](src/pages/components/tabs.mdx): Organises related content into selectable panels within a single view. Use to reduce cognitive load when content can be meaningfully divided into discrete sections. Don't use when all content should be visible simultaneously. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=449-8232 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-tabs--docs)
- [Tag](src/pages/components/tag.mdx): A compact label representing a metadata value, category, or filter applied to content. Use to display user-applied or system-assigned classifications that can be removed. Don't use for read-only status values — use Badge or Pill instead. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=183-6375 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-tag--docs)
- [Tag Group](src/pages/components/tag-group.mdx): A container for displaying and managing multiple tags together. Use when content can carry multiple simultaneous tag values. Don't use when only one tag value is possible.
- [Tooltip](src/pages/components/tooltip.mdx): Displays brief contextual information on hover or focus of a UI element. Use to clarify icon-only buttons or provide supplementary detail. Don't put essential information in a tooltip — it must be accessible without hover. (Figma: https://www.figma.com/design/s44WwKApTEJgB8qZpn9h3u/Orbit---Components?node-id=469-3036 · Storybook: https://orbit-storybook-seven.vercel.app/?path=/docs/orbit-tooltip--docs)

## Patterns

- [Patterns overview](src/pages/patterns/index.astro): Reusable solutions to common interaction and layout problems across Open Point and Social Point.
- [Forms & multi-step flows](src/pages/patterns/forms-and-flows.mdx): Chunking long forms, wizard and stepper flows, and inline validation and error handling.
- [Empty states](src/pages/patterns/empty-states.mdx): What a screen shows when there is no data — first-use, no-results, and no-permission.
- [Destructive-action confirmation](src/pages/patterns/destructive-actions.mdx): The modal and confirmation-dialog copy flow that guards irreversible actions.
- [Notifications & feedback](src/pages/patterns/notifications-and-feedback.mdx): Choosing between transient toast, inline alert, and modal — matching interruption to severity.

## Data Visualisation

- [Overview](src/pages/data-viz/overview.astro): Why data visualisation matters in community and stakeholder engagement, guiding principles, and how the Open Point colour palette maps to charts and tables.
- [Accessibility](src/pages/data-viz/accessibility.mdx): Requirements and best practices for making data visualisations perceivable and operable for all users — covering colour contrast, text alternatives, keyboard access, and screen reader patterns.
- [Colour in charts](src/pages/data-viz/colour-in-charts.mdx): How to use the Open Point colour system in data visualisation — categorical sequences, sequential palettes, diverging palettes, token references, and accessibility requirements.
- [Bar chart](src/pages/data-viz/chart-types/bar-chart.mdx): Compare values across categories using horizontal or vertical bars. Guidance on when to use bar charts, variants, anatomy, and accessibility requirements in Open Point products.
- [Line chart](src/pages/data-viz/chart-types/line-chart.mdx): Show trends over time using connected data points. Guidance on when to use line charts, variants, anatomy, and accessibility requirements in Open Point products.
- [Area chart](src/pages/data-viz/chart-types/area-chart.mdx): Show volume or cumulative magnitude over time using filled regions beneath a line. Guidance on when to use area charts, variants, anatomy, and accessibility in Open Point products.
- [Pie and donut](src/pages/data-viz/chart-types/pie-donut.mdx): Show part-to-whole relationships using circular segments. Guidance on when to use pie and donut charts, variants, anatomy, and accessibility in Open Point products.
- [Scatter plot](src/pages/data-viz/chart-types/scatter-plot.mdx): Reveal correlations or distributions between two quantitative variables. Guidance on when to use scatter plots, variants, anatomy, and accessibility in Open Point products.
- [Maps](src/pages/data-viz/maps.mdx): Display geographic or spatial data using interactive maps. Guidance on when to use maps, choropleth and point map patterns, and accessibility requirements in Open Point products.

## Content & Writing

- [Overview](src/pages/content-writing/overview.astro): Why writing is a design decision, who this section is for, and how to use the content guidelines in the Orbit.
- [Voice & tone](src/pages/content-writing/voice-and-tone.mdx): Open Point's voice attributes and how tone shifts by context — the foundation for all content in the Orbit.
- [Action labels](src/pages/content-writing/ui-text/action-labels.mdx): How to write clear, specific button and link labels in Open Point — verb-object patterns, destructive actions, and icon-only accessibility.
- [Empty states](src/pages/content-writing/ui-text/empty-states.mdx): How to write empty states in Open Point — four types, tone requirements, and how to avoid leaving users directionless.
- [Error messages](src/pages/content-writing/ui-text/error-messages.mdx): How to write error messages in Open Point — what went wrong, why it happened, and what to do next. Never blame, never alarm.
- [Form labels & helper text](src/pages/content-writing/ui-text/form-labels.mdx): How to write form labels, helper text, and placeholder text in Open Point — and why placeholder text is never a substitute for a label.
- [Notifications & alerts](src/pages/content-writing/ui-text/notifications.mdx): How to write clear, appropriately toned notification and alert copy in Open Point products — success, error, warning, and info patterns.
- [Confirmation dialogs](src/pages/content-writing/ui-text/confirmation-dialogs.mdx): How to write confirmation dialog copy in Open Point products — title, body, action labels, and the pattern for truly irreversible actions.
- [Capitalisation](src/pages/content-writing/formatting/capitalisation.mdx): Capitalisation rules for Open Point products — sentence case as default, proper nouns, all-caps usage, and common mistakes to avoid.
- [Numbers & dates](src/pages/content-writing/formatting/numbers-and-dates.mdx): Number and date formatting conventions for Open Point products — date formats, time zones, engagement metrics, and display conventions for a global audience.
- [Punctuation](src/pages/content-writing/formatting/punctuation.mdx): Punctuation conventions for Open Point products — Oxford comma, dashes, ellipsis, apostrophes, exclamation marks, and list punctuation rules.
- [Inclusive language](src/pages/content-writing/inclusive-language.mdx): Inclusive language guidance for Open Point products — people-first language, avoiding assumptions, community participation terminology, and a terminology reference table.
- [Writing for accessibility](src/pages/content-writing/writing-for-accessibility.mdx): Accessibility writing guidance for Open Point products — plain language, reading levels, screen reader copy, link text, alt text, error messages, and cognitive accessibility.