# AINDF — AI-Native Design Framework

> AINDF is a specification (not a code library) for building design systems that an AI agent can discover, reason about, generate, and validate — while remaining fully usable by humans. A design system is AI-Native when it is expressed as a graph of machine-readable contracts, derived from a single source, and enforced automatically. AINDF defines only the shape of those contracts; a conformant design system ships its own tokens, components, and brand. Version 0.1 (draft). Site: https://aindf.oleg.design — Source: https://github.com/0leg-design/ai-native-design-framework

## Six principles of an AI-Native design system

1. Semantic, intent-based naming — name by intent, not appearance (role/on-accent, never white).
2. Machine-readable contracts — every relationship declared in a schema; no inference from prose.
3. Closed, enforced choice space — valid combinations are finite; `when` predicates gate modifiers; a linter rejects the rest.
4. Slot + nesting contracts — what can be placed inside what is declared via slot.accepts.
5. One source, many generated outputs — docs, types, lint rules and the MCP surface are generated from one canonical spec.
6. Agent-navigable surface + conformance — the system answers MCP queries; a validator confirms declared conformance.

## Pages

- [Home](https://aindf.oleg.design/): the question "What makes a design system AI-native?" answered principle by principle, with who implements each today.
- [Spec](https://aindf.oleg.design/spec): the ten-section specification — thesis, contract graph, axes, token tiers, modifiers, presets, single-source, conformance, boundary, versioning.
- [Schemas](https://aindf.oleg.design/schemas): the six JSON Schema files of the contract graph, with field-level descriptions.
- [Examples](https://aindf.oleg.design/examples): three starter patterns — newsletter, chat, feature-grid — with clarifying parameters.
- [For agents](https://aindf.oleg.design/for-agents): the four-tool MCP surface — list-by-facet, slot-accepts, applicable-modifiers, get-preset.
- [Implementations](https://aindf.oleg.design/implementations): design systems that ship AINDF; Malevich is the reference implementation.

## Canonical artifacts (source of truth)

- [SPEC.md](https://github.com/0leg-design/ai-native-design-framework/blob/main/SPEC.md): the full specification.
- [tokens.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/tokens.schema.json): design tokens across three tiers with scopes.
- [taxonomy.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/taxonomy.schema.json): components classified on layer, role, renderTarget.
- [slots.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/slots.schema.json): slot contracts — accepts, cardinality, order.
- [applicability.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/applicability.schema.json): modifier→target and token-family→property rules with `when` gates.
- [presets.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/presets.schema.json): pre-composed instances with slots filled.
- [patterns.schema.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/schemas/patterns.schema.json): parametrized composition recipes.
- [patterns/starter.json](https://github.com/0leg-design/ai-native-design-framework/blob/main/patterns/starter.json): three starter patterns.

## MCP tools (read the schema each tool draws from)

- list-by-facet — enumerate components by axis (layer · role · renderTarget · interaction). Reads taxonomy.
- slot-accepts — given a slot, return accepts, cardinality, order. Reads slots.
- applicable-modifiers — given a component + context, return legal and excluded modifiers with a reason. Reads applicability.
- get-preset — resolve a preset name to a typed composition tree with slots filled. Reads presets and patterns.

## Notes

- License: MIT. Status: draft 0.1, co-evolving with its first reference implementation (Malevich); 1.0 will not be tagged before a real implementation has proven the spec.
- The dependency arrow is one-way: implementation → design system → framework.