# How the system fits together

OODS Foundry, the object-oriented design system, builds a screen from objects, traits, contexts, components and tokens. Here's each one, using the Harbor example from the quickstart.

Generated from @oods/foundry 0.10.1

## Objects: the things your product is made of

A Warehouse, a Subscription, a Quote. An object lists its own fields and the traits it's built from. OODS Foundry ships 11 business objects, and you can add your own or replace a shipped one.

[Objects](https://oods-foundry.com/objects)

The Harbor quickstart's object: `quickstart/Warehouse.object.yaml`

```
# A team's own object: a storage site the team ships orders from. It composes the team's Stockable trait beside two
# shipped ones. monthly_rent is a money amount in major units (12500.50 means 12,500.50), declared by its
# semantics; nothing is inferred from its name.
object:
  name: Warehouse
  version: 1.0.0
  domain: acme.logistics
  description: A storage site the team ships orders from.
  tags:
    - logistics
    - inventory

traits:
  - name: lifecycle/Stateful
    parameters:
      states:
        - planned
        - active
        - closed
      initialState: planned
  - name: lifecycle/Timestampable
    parameters:
      recordedEvents:
        - opened
        - restocked
        - closed
      timezone: UTC
  - name: Stockable
    parameters:
      capacityUnit: pallets

schema:
  # These examples describe operating sites with stock on hand. Independent enum
  # rotation paired a closed site with the trait's full-stock example.
  status:
    type: string
    required: true
    description: Current operating state of the warehouse.
    validation:
      enum:
        - planned
        - active
        - closed
    examples:
      - active
  last_event:
    type: string
    required: false
    description: Most recent recorded warehouse event.
    validation:
      enum:
        - opened
        - restocked
        - closed
    examples:
      - restocked
  last_event_at:
    type: datetime
    required: false
    description: When the sample warehouse was last restocked.
    examples:
      - '2026-09-15T12:00:00Z'
  # One history for every sample site: registered as planned, opened on 2 March, restocked since. The status
  # timeline reads state_history, not last_event, so the example authors the transition that made each site active.
  created_at:
    type: datetime
    required: true
    description: When the site was registered.
    examples:
      - '2026-01-12T09:00:00Z'
  updated_at:
    type: datetime
    required: false
    description: When the site's record last changed.
    examples:
      - '2026-09-15T12:00:00Z'
  state_history:
    type: StateTransition[]
    required: false
    description: The site's operating-state changes, oldest first.
    examples:
      - - title: Opened
          from: planned
          to: active
          at: '2026-03-02T08:00:00Z'
          reason: Site opened for orders
  warehouse_id:
    type: uuid
    required: true
    description: Unique identifier for the warehouse.
  name:
    type: string
    required: true
    description: The warehouse's name.
    examples:
      - Lakeside Distribution
      - North Yard
      - Harbor Cold Store
      - Prairie Crossdock
      - Riverbend Fulfillment
      - Summit Parts Depot
      - Bayview Returns Center
      - Canal Street Annex
      - Maple Grove Storage
      - Eastgate Freight Hub
  code:
    type: string
    required: true
    description: Short site code printed on shipping labels.
    examples:
      - MKE-01
      - CHI-02
      - DET-03
      - DSM-04
      - STL-05
      - DEN-06
      - OAK-07
      - IND-08
      - MSP-09
      - CLE-10
  city:
    type: string
    required: true
    description: City the warehouse is in.
    examples:
      - Milwaukee
      - Chicago
      - Detroit
      - Des Moines
      - St. Louis
      - Denver
      - Oakland
      - Indianapolis
      - Minneapolis
      - Cleveland
  manager_email:
    type: email
    required: false
    description: Who runs the site day to day.
    examples:
      - mke-01.manager@harbor.example
      - chi-02.manager@harbor.example
      - det-03.manager@harbor.example
      - dsm-04.manager@harbor.example
      - stl-05.manager@harbor.example
      - den-06.manager@harbor.example
      - oak-07.manager@harbor.example
      - ind-08.manager@harbor.example
      - msp-09.manager@harbor.example
      - cle-10.manager@harbor.example
  monthly_rent:
    type: number
    required: true
    description: What the site costs each month, in major units of its currency.
    examples:
      - 12500.5
      - 9800
      - 15250.75
      - 7400
      - 11850.25
      - 21000
      - 18990.99
      - 6250
      - 9975.5
      - 14300
  currency:
    type: string
    required: true
    description: Currency the rent is paid in.
    validation:
      enum:
        - USD
        - EUR
        - GBP

  organization_id:
    type: uuid
    required: false
    description: The organization operating this warehouse.
    examples:
      - 5d0c6a2e-8f41-4b7a-9c3e-2a6f1b8d4e90
  organization_name:
    type: string
    required: false
    description: The operating organization's name, shown in place of its id.
    examples:
      - Harbor Logistics

relationships:
  - target: Organization
    via: organization_id
    cardinality: many-to-one
    label: Operated by

semantics:
  name:
    semantic_type: logistics.warehouse.name
    token_mapping: tokenMap(text.primary)
  monthly_rent:
    semantic_type: logistics.warehouse.rent
    token_mapping: tokenMap(commerce.price.primary)
    ui_hints:
      component: CurrencyAmount
      currencyField: currency
  currency:
    semantic_type: logistics.warehouse.currency
    token_mapping: tokenMap(commerce.currency.primary)
  organization_id:
    semantic_type: logistics.warehouse.operator
    token_mapping: tokenMap(text.body.*)
    ui_hints:
      displayLabelField: organization_name

metadata:
  owners:
    - logistics-team
  maturity: beta
```

## Traits: capabilities objects share

Being stocked, having a price, moving through states. A trait adds fields and says what to show in each context. Define it once, and every object that has it gets it. OODS Foundry ships 49.

[Traits](https://oods-foundry.com/traits)

Its trait: `quickstart/Stockable.trait.yaml`

```
trait:
  name: Stockable
  version: 1.0.0
  description: How full a storage location is, counted in the unit the team stores goods in.
  category: inventory
  tags:
    - inventory
    - capacity

parameters:
  - name: capacityUnit
    type: string
    required: false
    description: The unit capacity and stock are counted in.
    default: pallets

schema:
  stock_level:
    type: string
    required: true
    description: Whether the location has room, is nearly full, or is full.
    validation:
      enum:
        - room_available
        - nearly_full
        - full
  capacity_units:
    type: integer
    required: true
    description: How many units the location holds when it is full.
    examples:
      - 1200
      - 800
      - 2400
  units_on_hand:
    type: integer
    required: true
    description: How many units are stored there now.
    examples:
      - 640
      - 760
      - 2400

semantics:
  stock_level:
    semantic_type: inventory.stock.level
    token_mapping: tokenMap(inventory.stock.*)
    ui_hints:
      component: StatusBadge

view_extensions:
  list:
    - component: StatusBadge
      position: after
      props:
        statusField: stock_level
        emphasis: subtle
        showIcon: false
  card:
    - component: StatusBadge
      position: after
      props:
        statusField: stock_level
        emphasis: subtle
        showIcon: false
  detail:
    - component: StatusBadge
      position: main
      priority: 70
      props:
        statusField: stock_level
        emphasis: subtle
        showIcon: false
    # Like the shipped Supersedable trait: the fields the trait is about are placed explicitly, so the detail
    # composer's field budget never leaves them out.
    - component: Text
      position: main
      priority: 69
      props:
        field: units_on_hand
    - component: Text
      position: main
      priority: 68
      props:
        field: capacity_units

tokens:
  inventory.stock.tone: neutral

dependencies: []
```

## Contexts: where an object shows up

The same Warehouse appears as a row in a list, a full detail page, a form, a timeline, a card, an inline mention, or a whole workflow app. There are 7 contexts.

Here is the quickstart's Warehouse, generated in each one by OODS Foundry 0.10.1 in Harbor's brand, the quickstart's example team brand, with the shipped components. [Contexts](https://oods-foundry.com/contexts)

- [detail](https://oods-foundry.com/contexts/detail)
- [list](https://oods-foundry.com/contexts/list)
- [form](https://oods-foundry.com/contexts/form)
- [timeline](https://oods-foundry.com/contexts/timeline)
- [card](https://oods-foundry.com/contexts/card)
- [inline](https://oods-foundry.com/contexts/inline)
- [workflow](https://oods-foundry.com/contexts/workflow)

[Warehouse detail screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/detail-react)

React app · sample records Maturity: beta `sha256:5e965cb869b5…` [Open full size: Warehouse detail screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/detail-react)

Vue app · sample records Maturity: beta `sha256:eb3203fccd62…` [Open full size: Warehouse detail screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/detail-vue)

React app · sample records Maturity: beta `sha256:8dec2f275d11…` [Open full size: Warehouse list screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/list-react)

Vue app · sample records Maturity: beta `sha256:af573e23b40b…` [Open full size: Warehouse list screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/list-vue)

React app · sample records Maturity: beta `sha256:8ae396e268b0…` [Open full size: Warehouse form screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/form-react)

Vue app · sample records Maturity: beta `sha256:1fc1dd6c1b78…` [Open full size: Warehouse form screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/form-vue)

React app · sample records Maturity: beta `sha256:b7340d420762…` [Open full size: Warehouse timeline screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/timeline-react)

Vue app · sample records Maturity: beta `sha256:7a7a3ae90e8a…` [Open full size: Warehouse timeline screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/timeline-vue)

React app · sample records Maturity: beta `sha256:e7ebc4613bcb…` [Open full size: Warehouse card screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/card-react)

Vue app · sample records Maturity: beta `sha256:3944c438e0db…` [Open full size: Warehouse card screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/card-vue)

React app · sample records Maturity: beta `sha256:b03b2e4e7c22…` [Open full size: Warehouse inline screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/inline-react)

Vue app · sample records Maturity: beta `sha256:a7dfa5ed96cf…` [Open full size: Warehouse inline screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/inline-vue)

React app · sample records Maturity: beta `sha256:4f27544ac326…` [Open full size: Warehouse workflow screen generated by OODS Foundry in React](https://oods-foundry.com/system/warehouse/workflow-react)

Vue app · sample records Maturity: beta `sha256:9c8b76ec2aeb…` [Open full size: Warehouse workflow screen generated by OODS Foundry in Vue](https://oods-foundry.com/system/warehouse/workflow-vue)

What `design_compose` reported for every screen here:

- `OODS-V121` Object 'Warehouse' has maturity 'beta' — composed output may change.
- `OODS-V117` Warehouse refines 6 fields its traits define, and its own definitions are used: lifecycle/Stateful (status, state_history); lifecycle/Timestampable (last_event, last_event_at, created_at, updated_at).

The calls that made the Warehouse detail apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "detail",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-c5105889",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-c5105889",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:5e965cb869b59fdd48c848733e32fa7a048290638481bfdd3772344886b955d4`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:eb3203fccd62a0b1147a61d4c2fa1b44a354ff66900bf2c699bf234b38a53d5c`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

The calls that made the Warehouse list apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "list",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-37cc58fb",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-37cc58fb",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:8dec2f275d11d9bfc00c85e02d20e3ae07097fc8df24e7cc80aaf04962084080`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:af573e23b40b9573dc4a719e4bd0e84fedda38a091b8c182e23edd2c8fda3d64`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

The calls that made the Warehouse form apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "form",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-f264d3f5",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-f264d3f5",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:8ae396e268b0d57ff376273cf6b1259fc53915167911b5569d30f6aee48f877f`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:1fc1dd6c1b784ed748d60726ff33986984e542ce75ecd4953566212fe76e08dd`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

For this screen it also reported:

- `OODS-V119` No view_extensions found for context "timeline" in object "Warehouse". Available contexts: list, detail, form, card

The calls that made the Warehouse timeline apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "timeline",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-8d1a3313",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-8d1a3313",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:b7340d420762275994440eca41abed8329251e3acb0398e921458652f6598b1e`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:7a7a3ae90e8acf0a88b1fbb256ce02df4655d4fc414696f08ae0962db925c8d9`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

The calls that made the Warehouse card apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "card",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-2b2b9dfc",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-2b2b9dfc",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:e7ebc4613bcbff3374111495a968a59c96b29c8869f09dfbef2fbbdad3c153e7`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:3944c438e0db7fa94ce8047d55e18a5726bb64ed0a881c80a8b5da1896cf56e6`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

For this screen it also reported:

- `OODS-V119` No view_extensions found for context "inline" in object "Warehouse". Available contexts: list, detail, form, card

The calls that made the Warehouse inline apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "inline",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-cbdba88a",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-cbdba88a",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:b03b2e4e7c22b62918dc47f71da265272a83691db2fb47010e6bd8f0de2376db`. Its `src/` folder: App.tsx, GeneratedUI.tsx, app.css, main.tsx, oods-brand-harbor.css

The Vue app's content hash: `sha256:a7dfa5ed96cfbda39b2f0d9d4e5b648098d4ed9ae84b7be2ceee06caf9a6f1ae`. Its `src/` folder: App.vue, GeneratedUI.vue, app.css, main.ts, oods-brand-harbor.css

For this screen it also reported:

- `OODS-V121` as above, 4 times in all
- `OODS-V117` as above, 4 times in all
- `OODS-V119` No view_extensions found for context "timeline" in object "Warehouse". Available contexts: list, detail, form, card

The calls that made the Warehouse workflow apps, in React and Vue

3 calls, as the pipeline sent them

```
design_compose {
  "object": "Warehouse",
  "context": "workflow",
  "preferences": {
    "brand": "Harbor",
    "theme": "light"
  }
}

code_generate {
  "schemaRef": "compose-3b1e22ab",
  "framework": "react",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}

code_generate {
  "schemaRef": "compose-3b1e22ab",
  "framework": "vue",
  "profile": "build",
  "options": {
    "output": "application",
    "brand": "Harbor",
    "theme": "light",
    "payloadMode": "file"
  }
}
```

The React app's content hash: `sha256:4f27544ac3261a4d95c0f0325a283716471c3dea7a5f82b8e02ef506626fa4bf`. Its `src/` folder: App.tsx, actions.ts, app.css, application.ts, main.tsx, oods-brand-harbor.css, sample-data.ts, screens/, ssr.tsx, store.ts

The Vue app's content hash: `sha256:9c8b76ec2aebc04a2528e1108a3d433dd9043bc94b86866968381eacb96773ae`. Its `src/` folder: App.vue, actions.ts, app.css, application.ts, main.ts, oods-brand-harbor.css, sample-data.ts, screens/, ssr.ts, store.ts

## Components: what screens are built from

OODS Foundry picks a component for every slot, by rule, from 114 governed components in React and Vue. You can map any of them to your own component.

[Components](https://oods-foundry.com/components)

The components the quickstart's Warehouse detail screen imports:

- [`Button`](https://oods-foundry.com/components/button)
- [`Card`](https://oods-foundry.com/components/card)
- [`DetailHeader`](https://oods-foundry.com/components/detail-header)
- [`PriceBadge`](https://oods-foundry.com/components/price-badge)
- [`Stack`](https://oods-foundry.com/components/stack)
- [`StatusBadge`](https://oods-foundry.com/components/status-badge)
- [`StatusTimeline`](https://oods-foundry.com/components/status-timeline)
- [`Tabs`](https://oods-foundry.com/components/tabs)
- [`Text`](https://oods-foundry.com/components/text)

## Tokens and brands: how it looks

Every colour, size and space comes from a token. A brand sets the tokens for light, dark and high contrast. OODS Foundry ships 2 brands, and you can make your own from a recipe or your own colour values.

[Foundations](https://oods-foundry.com/foundations) · [Brands](https://oods-foundry.com/brands)

Harbor's colour values, its first lines: `quickstart/harbor.tokens.json`

```
{
  "base": {
    "surface": {
      "canvas": {
        "$type": "color",
        "$value": "oklch(1 0.000007 205)",
        "$description": "Primary application canvas."
      },
      "raised": {
        "$type": "color",
        "$value": "oklch(1 0.000007 205)",
        "$description": "Raised card surface."
      },
      "subtle": {
        "$type": "color",
        "$value": "oklch(0.97 0.00288 205)",
        "$description": "Subtle secondary surface."
      },
      "disabled": {
        "$type": "color",
        "$value": "oklch(0.97 0.00288 205)",
        "$description": "Surface colour for disabled or inactive UI."
      },
      "backdrop": {
```

Your assistant makes the calls. OODS Foundry composes the screen by rule, generates the code, and hands back a receipt of what it checked.