Menu
v0.10.1

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

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

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

React app · sample recordsMaturity: betasha256:5e965cb869b5…Open full size

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

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

The components the quickstart's Warehouse detail screen imports:

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 · 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.