Design Intent Ownership Bible 2.0

Penpot-Primary, Figma-Compatible, Canva Pro Marketing Methodology Primer

Version: 2.0 (2026) Status: Production-Ready Methodology Architecture: Endpoint-Agnostic with Local Developer Integration Baseline

---

Table of Contents

1. [Foundations & Philosophy](#section-1--foundations--philosophy)
2. [Tool Ownership Boundaries](#section-2--tool-ownership-boundaries)
3. [Penpot Comprehensive Definition](#section-3--penpot-comprehensive-definition)
4. [Bi-Directional Sync Pipeline](#section-4--bi-directional-sync-pipeline)
5. [Code Sync to Hosting Targets](#section-5--code-sync-to-hosting-targets)
6. [AI Agent Orchestration Detail](#section-6--ai-agent-orchestration-detail)
7. [Lifecycle Management](#section-7--lifecycle-management)
8. [Operational Runbook](#section-8--operational-runbook)

---

SECTION 1 — FOUNDATIONS & PHILOSOPHY

Why Penpot-Primary with Figma and Canva as Complements

The Three-Tool Strategy

This methodology establishes a tiered design tool architecture optimized for design intent ownership, code synchronization, and marketing agility:

1. Penpot (Primary): Open-source, self-hosted design tool with native code sync capabilities
2. Figma (Secondary): Industry-standard tool for existing brand assets and team collaboration
3. Canva Pro (Tertiary): Marketing iteration and rapid content production

Why Penpot as Primary?

• Open Standards: SVG-native, HTML/CSS output, no proprietary lock-in
• Self-Hosted Control: Deploy anywhere (local Docker, Raspberry Pi, VPS, AWS, Kubernetes)
• MCP Integration: Native Model Context Protocol server for AI-agent orchestration
• Code Adjacency: Designed for design-to-code workflows from inception
• Bi-directional Potential: Architecture supports true design ↔ code sync
• Cost: Open-source (no per-seat licensing), production-ready as of 2.x

Why Figma as Secondary?

• Industry Momentum: Existing brand assets, team familiarity, vendor ecosystem
• Collaboration: Superior real-time multi-user editing and commenting
• Branching: Git-style version control for design
• Plugin Ecosystem: Tokens Studio, extensive community plugins
• Transition Strategy: Maintain existing assets while building Penpot-primary future

Why Canva Pro as Tertiary?

• Marketing Velocity: Rapid iteration for social media, ads, presentations
• Template Ecosystem: Pre-built templates for common marketing formats
• Brand Kit: Centralized brand assets for consistency
• Non-Designer Friendly: Enables marketing team self-service
• Not for Design Systems: Explicitly not for component library or token management

Design Intent Ownership Defined

Design Intent = The authoritative expression of what the design should be and why, distinct from how it is implemented in code.

Ownership Model (2026 Consensus)

The Design Control Schema (DCS) Concept

The DCS is the reconciliation bridge—a versioned, structured metadata layer that maps design intent to code implementation:

{
  "component": "Button",
  "designId": "figma://component/button-primary",
  "codeId": "@design-system/button",
  "version": "2.1.0",
  "mappings": {
    "designProperty": "variant",
    "codeProperty": "variant",
    "valueMap": {
      "Primary": "primary",
      "Secondary": "secondary"
    }
  },
  "tokens": {
    "background": "{color.action.primary}",
    "padding": "{spacing.md}"
  },
  "lastSync": "2026-05-22T10:30:00Z"
}

The DCS enables:

• Design and code to evolve semi-independently
• Automated conflict detection
• Version tracking across design/code boundaries
• Agent-mediated reconciliation

Industry-Language Alignment

W3C Design Tokens Community Group (DTCG) Standard

Design Tokens: Indivisible pieces of a design system (colors, spacing, typography) stored in technology-agnostic format.

DTCG Format (v2025.10):

{
  "color-primary": {
    "$type": "color",
    "$value": "#0066cc",
    "$description": "Primary brand color"
  },
  "spacing-base": {
    "$type": "dimension",
    "$value": "16px"
  }
}

Token Hierarchy:

1. Base/Primitive: Raw values (color-base-blue-500: #0969DA)
2. Semantic/Functional: Purpose-driven (color-action-primary: {color-base-blue-500})
3. Component: Component-specific (limited use)

Atomic Design (Brad Frost, 2024-2025 Update)

• Subatomic: Design tokens (foundational layer)
• Atoms: Foundational UI elements (button, input, label)
• Molecules: Simple groups of atoms (search form)
• Organisms: Complex components (header with nav)
• Templates: Page layouts with placeholder content
• Pages: Templates with real content

Key Component Terminology

• Components: Reusable UI elements with defined API
• Variants: Different versions (Button: primary, secondary, destructive)
• Slots: Designated areas for content insertion
• Patterns: Reusable component combinations solving UX problems
• Templates: Page-level layouts combining patterns

---

SECTION 2 — TOOL OWNERSHIP BOUNDARIES

Penpot: Primary Design Tool & Code Sync Hub

Canonical Responsibilities

• Component Library (Master): All design system components authored in Penpot
• Design Token Source (Co-Primary): Exports tokens in DTCG format
• Code Sync Integration Point: MCP server provides AI-agent access
• Version Control: Native file versioning
• Developer Handoff: Automatic code generation

Anti-Patterns

• ❌ Marketing collateral (use Canva Pro)
• ❌ Real-time collaboration for >5 designers (use Figma)
• ❌ Production code logic (code repository owns)

Native Capabilities

• Design Tokens: Native DTCG export (since 2.x)
• Components: Main components, instances, variants
• Governance: Team permissions, file-level access
• Code Adjacency: HTML/CSS export, plugin API

Figma: Secondary Design Tool & Collaboration Hub

Canonical Responsibilities

• Existing Brand Assets: Maintain pre-existing Figma libraries
• Real-Time Collaboration: Multi-designer workshops
• Stakeholder Review: Client presentations, prototyping
• Token Sync (Inbound): Variables populated FROM code repository

Anti-Patterns

• ❌ Net-new component creation (create in Penpot)
• ❌ Source of truth for tokens (tokens live in code)
• ❌ Long-term storage without Penpot mirror

Custom Plugin to Replicate Code Connect

Since Code Connect requires Organization tier, build custom plugin using plugin data storage:

// Store component-code mappings
function storeCodeMapping(component: ComponentNode, mapping: CodeMapping) {
  component.setSharedPluginData('code-connect-manual', 'mapping', JSON.stringify({
    componentPath: 'src/components/Button.tsx',
    componentName: 'Button',
    framework: 'React',
    propMappings: [...],
    importStatement: 'import { Button } from "@/components/Button"',
    lastUpdated: Date.now()
  }));
}

Canva Pro: Marketing Iteration Add-On

Canonical Responsibilities

• Social Media Graphics
• Ad Creative & A/B test variants
• Presentation Decks
• Email Graphics

Anti-Patterns

• ❌ Design system components
• ❌ Design tokens
• ❌ Developer handoff
• ❌ Website design

Integration: One-way (Design System → Canva Brand Kit), manual token updates

---

SECTION 3 — PENPOT COMPREHENSIVE DEFINITION

Penpot Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                Frontend (ClojureScript + React)          │
│                    Port 9001 (Nginx)                     │
└───────────────────────┬─────────────────────────────────┘
                        │ RPC API + WebSocket
┌───────────────────────┴─────────────────────────────────┐
│              Backend (Clojure/JVM, Port 6060)           │
└────────┬────────────┬─────────────┬─────────────────────┘
         │            │             │
    ┌────┴────┐  ┌───┴────┐   ┌───┴────────┐
    │PostgreSQL│  │ Valkey │   │  Exporter  │
    │  15+    │  │ (Redis)│   │  (Node.js) │
    └─────────┘  └────────┘   └─────┬──────┘
                                     │
                                ┌────┴────────┐
                                │   Object     │
                                │Storage (S3) │
                                └─────────────┘

Components:

• Frontend: ClojureScript + React SPA
• Backend: Clojure on JVM, custom RPC API
• Exporter: Node.js with Puppeteer for PNG/PDF exports
• PostgreSQL: Primary data persistence (15+ recommended)
• Valkey: Message broker for real-time collaboration
• Object Storage: S3-compatible or filesystem

Endpoint-Agnostic Deployment Model

Configuration Contract:

PENPOT_PUBLIC_URI: "https://penpot.yourdomain.com"
PENPOT_SECRET_KEY: "<64-byte-random-string>"
PENPOT_DATABASE_URI: "postgresql://host:5432/penpot"
PENPOT_REDIS_URI: "redis://host:6379/0"
PENPOT_OBJECTS_STORAGE_BACKEND: "fs" # or "s3"

Deployment Options:

1. Local Docker Compose (Development Baseline):

wget https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml
docker compose up -d
# Access: http://localhost:9001

1. VPS (Vultr/DigitalOcean): Docker Compose + Nginx reverse proxy + SSL
2. Kubernetes: Official Helm chart (helm install penpot penpot/penpot)
3. AWS: ECS Fargate or EKS with RDS PostgreSQL, ElastiCache, S3

Reverse Proxy Example (Nginx):

server {
    listen 443 ssl;
    server_name penpot.yourdomain.com;
    client_max_body_size 367001600;
    
    location /ws/notifications {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_pass http://localhost:9001/ws/notifications;
    }
    
    location / {
        proxy_pass http://localhost:9001/;
    }
}

Local Developer Environment (Always-Available Baseline)

Purpose: Local Penpot provides consistent API endpoint for development, AI agents, CI/CD.

Setup:

mkdir penpot-dev && cd penpot-dev
wget https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml
# Customize: disable email verification, disable secure cookies
docker compose up -d

Development Integrations:

• VSCode/Cursor: MCP server for AI-assisted workflows
• Local Testing: Component rendering against live Penpot
• Automation Scripts: API access for bulk operations

Backup and Restore

# Database backup
docker exec penpot-postgres pg_dump -U penpot penpot > penpot-backup.sql

# Assets backup
docker run --rm -v penpot_assets:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/penpot-assets-$(date +%Y%m%d).tar.gz /data

# Restore
docker exec -i penpot-postgres psql -U penpot penpot < penpot-backup.sql

Authentication Options

• Built-in: Email/password
• OAuth: Google, GitHub, GitLab
• OIDC: Enterprise SSO (Azure AD, Okta, etc.)
• LDAP: Active Directory integration

API Surface

Available in Self-Hosted:

• Custom RPC API (full CRUD operations)
• Webhooks (with enable-webhooks flag)
• Export API (PNG, SVG, PDF)
• Access tokens for authentication

Example:

curl -H "Authorization: Token <your-token>" \
  https://penpot.yourdomain.com/api/rpc/command/get-profile

Plugin System and MCP Integration

Plugin Architecture:

• Manifest: manifest.json with permissions
• Code: JavaScript (compile TypeScript with @penpot/plugin-types)
• UI: Optional HTML interface

MCP Integration (Since 2.15.0):

AI Client (Claude/Cursor) → MCP Server (port 4401) → Penpot Plugin → Penpot

Configuration (Claude Desktop):

{
  "mcpServers": {
    "penpot": {
      "command": "node",
      "args": ["/path/to/penpot/mcp-server/dist/index.js"],
      "env": {
        "PENPOT_MCP_SERVER_ADDRESS": "http://localhost:4401"
      }
    }
  }
}

---

SECTION 4 — BI-DIRECTIONAL SYNC PIPELINE

Architecture Overview

Penpot/Figma Design → DCS (Design Control Schema) ↔ GitHub Tokens Repo
                                                    ↓
                                            Style Dictionary
                                                    ↓
                                    Platform Code (CSS/iOS/Android/React)
                                                    ↓
                                            Production Sites

Code Repository Changes → DCS Validation → Conflict Detection → Resolution
                                                               ↓
                                            Design Tool Update (via API/Plugin)

Key Principle: Design and code are both sources of truth in their respective domains. The DCS serves as the reconciliation bridge.

True Bi-Directional Sync with Conflict Resolution

2024-2026 Reality: True automated bi-directional sync doesn't exist at scale. What exists: Bi-directional workflows with human-in-the-loop conflict resolution.

Design → Code Flow:

1. Design Change (Penpot/Figma)
2. Detection (webhook/polling)
3. DCS Update (extract changes, generate diff)
4. Validation (schema, accessibility, naming)
5. Code Generation (Style Dictionary, component scaffolding)
6. Review & Merge (automated tests + human review)

Code → Design Flow:

1. Code Change (GitHub commit)
2. Detection (Git commit triggers DCS sync)
3. DCS Comparison (identify discrepancies)
4. Conflict Classification (orthogonal/complementary/conflicting)
5. Design Tool Update (auto-update or flag for review)
6. Review & Reconciliation (designer approves/rejects)

Conflict Resolution Model

Conflict Types:

Conflict Detection:

interface ConflictDetector {
  compareTokens(designTokens, codeTokens): Conflict[];
  compareComponents(designComponent, codeComponent): Conflict[];
  detectBreakingChanges(oldDCS, newDCS): BreakingChange[];
}

// Example conflict output
{
  type: "value_mismatch",
  property: "color-primary",
  designValue: "#0066cc",
  codeValue: "#0055bb",
  confidence: 1.0,
  suggestedResolution: "manual_review"
}

Resolution Workflows:

• High Confidence (≥80%): Auto-resolve and notify
• Medium Confidence (50-80%): Present options, await approval
• Low Confidence (<50%): Escalate to human immediately

Script-Level Sync: CLI Tools

#!/bin/bash
# dcs-sync.sh

case $1 in
  design-to-code)
    node scripts/export-penpot-tokens.js
    node scripts/update-dcs.js --source=penpot
    npm run tokens:build
    node scripts/create-pr.js --source=design
    ;;
  code-to-design)
    node scripts/parse-code-changes.js
    node scripts/update-dcs.js --source=code
    node scripts/detect-conflicts.js
    node scripts/update-penpot.js
    ;;
esac

Plugin-Level Sync

Figma Plugin (Manual Code Connect):

// Fetch DCS from GitHub
const dcs = await fetchDCS('https://api.github.com/repos/org/repo/contents/dcs.json');

// Compare with Figma components
components.forEach(component => {
  const dcsEntry = dcs.components.find(c => c.designId === component.key);
  if (conflictDetected) {
    flagForReview(component);
  } else {
    storeCodeMapping(component, dcsEntry);
  }
});

AI Agent Skills and Orchestration

Orchestration Pipeline:

Coordinator Agent:
  - Detects changes (webhooks, Git commits)
  - Routes to specialists (Token, Component, Layout, Validation)
  - Aggregates results
  - Handles conflict resolution
  - Updates DCS, generates PRs

Specialist Agents:

Token Extraction Agent:

skills:
  - Extract design tokens from Penpot/Figma
  - Normalize to DTCG format
  - Validate against schema
  - Generate diff from previous version
outputs:
  - tokens.json (DTCG)
  - change_report.json

Component Mapping Agent:

skills:
  - Analyze design component structure
  - Match to existing code components
  - Generate prop mappings
  - Create code scaffold for new components
outputs:
  - component_mapping.json
  - code_scaffold/

Layout Agent:

skills:
  - Detect layout patterns (flex, grid)
  - Infer responsive behavior
  - Generate CSS/styled-components
outputs:
  - layout.css
  - responsive_rules.json

Validation Agent:

skills:
  - Visual regression testing (Percy/Chromatic)
  - Accessibility audit (axe-core)
  - Performance checks (Lighthouse)
  - Semantic diff (breaking changes)
outputs:
  - validation_report.json
  - pass/fail status

Pipeline Phases: Define → Bind → Refine

Style Tokens:

• Define: Create primitive and semantic tokens, export to DTCG
• Bind: Apply tokens to all components, replace hard-coded values
• Refine: Optimize token set, monitor for drift

Components:

• Define: Design component with variants, props, token usage
• Bind: Implement in code, wire up tokens, create Storybook stories
• Refine: Iterate based on usage feedback, A/B test improvements

Patterns/Templates:

• Buildout: Compose components into patterns, define responsive behavior
• Adaptive Responsive Audit: Test across breakpoints [320px, 768px, 1024px, 1440px]
• Validation: Layout integrity, touch targets, content visibility

Ingest Pipeline (HTML/Image/Code → Design System)

HTML Ingest:

1. Crawl production site (Puppeteer/Playwright)
2. AI analysis (extract patterns, colors, typography)
3. Token extraction (cluster colors, normalize fonts)
4. Component detection (identify repeated patterns)
5. Figma/Penpot recreation

Image Ingest (Screenshot → Components):

1. AI Vision analysis (GPT-4 Vision/Claude 3)
2. Token matching (map to existing palette)
3. Component specification
4. Designer recreation from spec

Code Ingest (Existing Code → Design System):

1. AST parsing (discover components)
2. Static analysis (hard-coded values vs. tokens)
3. Visual extraction (render and capture)
4. Token reverse engineering
5. Design tool mirroring

---

SECTION 5 — CODE SYNC TO HOSTING TARGETS

(A) Static Site Generators

Recommended: Astro, Eleventy, Next.js (static export), Hugo

Token Pipeline:

DTCG JSON → Style Dictionary → CSS Custom Properties → SSG → Static HTML/CSS

Style Dictionary Config:

export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'design-tokens.css',
        format: 'css/variables',
        options: { outputReferences: true }
      }]
    }
  }
};

Astro Component Example:

---
interface Props {
  variant?: 'primary' | 'secondary';
}
const { variant = 'primary' } = Astro.props;
---

<button class={`btn btn--${variant}`}>
  <slot />
</button>

<style>
  .btn {
    padding: var(--spacing-md) var(--spacing-lg);
    border-radius: var(--border-radius-base);
  }
  .btn--primary {
    background: var(--color-action-primary);
  }
</style>

Build/Deploy (GitHub Actions):

name: Deploy Astro Site
on: [push]
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run tokens:build
      - run: npm run build
      - uses: vercel-action@v20

(B) Headless CMS

Recommended: Sanity, Strapi, Payload, Directus

Token Pipeline:

DTCG JSON → Style Dictionary → CSS Variables + JSON API → CMS Preview + Frontend

Sanity Integration:

// sanity.config.ts - Theme Studio with tokens
import tokens from './design-tokens.json';

export default defineConfig({
  theme: {
    '--brand-primary': tokens.colors.primary,
    '--radius-base': tokens.borderRadius.base
  }
});

// Content references design system components
{
  name: 'component',
  type: 'object',
  fields: [
    {
      name: 'type',
      type: 'string',
      options: {
        list: ['Hero', 'Features', 'CTA']
      }
    }
  ]
}

Frontend Rendering (Next.js + Sanity):

// Fetch content from Sanity
const pageData = await sanityClient.fetch(`*[_type == "page"][0]`);

// Render with design system components
pageData.content.map(block => {
  const Component = componentMap[block.type];
  return <Component {...block} />;
});

(C) WordPress

Modern WordPress: Block Themes + theme.json

Token Pipeline:

DTCG JSON → Custom Transform Script → theme.json → WordPress Global Styles

Transform Script:

// build-theme-json.js
const tokens = require('../design-tokens.json');

const themeJson = {
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": Object.entries(tokens.colors).map(([key, value]) => ({
        "slug": key,
        "color": value,
        "name": key.charAt(0).toUpperCase() + key.slice(1)
      }))
    },
    "typography": {
      "fontSizes": Object.entries(tokens.fontSize).map(([key, value]) => ({
        "slug": key,
        "size": value
      }))
    }
  }
};

fs.writeFileSync('theme.json', JSON.stringify(themeJson, null, 2));

Custom Block with Tokens:

// Custom block using theme tokens
registerBlockType('mytheme/custom-card', {
  edit: ({ attributes }) => {
    const blockProps = useBlockProps({
      className: `card card--${attributes.variant}`
    });
    return <div {...blockProps}>Content</div>;
  }
});

// Block styles using WordPress CSS variables
.card {
  background: var(--wp--preset--color--base);
  padding: var(--wp--preset--spacing--lg);
  border-radius: var(--wp--custom--border-radius--base);
}

---

SECTION 6 — AI AGENT ORCHESTRATION DETAIL

Multi-Agent Specialist Pattern

Architecture: Coordinator + Domain Specialists

Coordinator Agent
    ├── Token Specialist (extraction, mapping)
    ├── Component Specialist (analysis, generation)
    ├── Layout Specialist (responsive, CSS)
    └── Validation Specialist (visual, a11y, performance)
            ↓
        Aggregator → Conflict Resolver → Final Output

Benefits:

• Specialization (optimized per domain)
• Parallelization (independent tasks run simultaneously)
• Failure isolation
• Clear observability

Agent Skill Definitions

Token Specialist:

skills:
  - extract_design_tokens (Figma/Penpot via MCP)
  - map_tokens_to_dcs
  - validate_token_usage (audit components)
tools:
  - penpot_mcp.get_tokens
  - figma_mcp.get_variables
  - style_dictionary.transform
outputs:
  - tokens.json (DTCG)
  - compliance_score

Component Specialist:

skills:
  - analyze_design_component (structure, props, variants)
  - map_to_code_component (DCS lookup)
  - generate_component_code (React/Vue/Web Components)
outputs:
  - component_spec.json
  - generated_code/
  - storybook_stories/

Layout Specialist:

skills:
  - analyze_layout_pattern (flex, grid, absolute)
  - infer_responsive_behavior
  - generate_layout_css
outputs:
  - layout.css
  - responsive_rules.json

Validation Specialist:

skills:
  - visual_regression_test (Percy/Chromatic)
  - accessibility_audit (axe-core, WCAG 2.1 AA)
  - performance_check (Lighthouse)
  - semantic_diff (breaking changes)
gates:
  - Visual match ≥95% (BLOCKING)
  - Zero A11y violations (BLOCKING)
  - Performance within budget (WARNING)

When to Use Single vs. Multi-Agent

Single Orchestrator: Simple tasks (<5 steps), well-defined workflows, prototyping

Multi-Agent Specialists: Complex workflows, parallel tasks, domain expertise needed, production systems

Validation Gates by Phase

Define Phase:

• DTCG schema validation (BLOCKING)
• Token naming conventions (BLOCKING)
• No duplicates (BLOCKING)

Bind Phase:

• Token compliance - no hard-coded values (BLOCKING)
• Accessibility structure (BLOCKING)

Refine Phase:

• Visual regression ≥95% (BLOCKING)
• Full WCAG 2.1 AA compliance (BLOCKING)
• Cross-browser (BLOCKING)
• Performance (WARNING - track but don't block)

Release Phase:

• Breaking change detection (BLOCKING if unintentional)
• Migration guide exists (BLOCKING for MAJOR)
• Documentation complete (BLOCKING)

Conflict Resolution Agent

Conflict Mediation Agent:
  inputs:
    - conflict_report
    - design_system_guidelines
    - historical_resolutions
  
  process:
    1. Classify conflict (orthogonal/complementary/conflicting)
    2. Gather context (docs, usage data, Git history)
    3. Generate recommendation with confidence score
    4. Execute (≥80%) or Escalate (<80%)
  
  learning:
    - Store all resolutions
    - Improve confidence scoring over time
    - Target 60-70% auto-resolution rate

MCP Server Integration

Architecture:

AI Agents use multiple MCP servers as tools:

- Figma MCP: get_design_context, get_variables
- Penpot MCP: get_board, get_tokens, modify_elements
- GitHub MCP: create_pull_request, search_code
- Custom DCS MCP: update_component_mapping, detect_conflicts

Configuration (Claude Desktop):

{
  "mcpServers": {
    "figma": { "type": "http", "url": "https://mcp.figma.com/mcp/" },
    "penpot": { "command": "node", "args": ["/path/to/mcp-server/dist/index.js"] },
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "dcs": { "type": "http", "url": "http://localhost:5000/mcp" }
  }
}

---

SECTION 7 — LIFECYCLE MANAGEMENT

Versioning Strategy

Semantic Versioning for Design Systems:

• MAJOR (x.0.0): Breaking changes (prop removed/renamed, token name changes)
• MINOR (1.x.0): New components, new variants, deprecations (additive)
• PATCH (1.1.x): Bug fixes, docs, non-breaking accessibility improvements

Versioning Per Layer:

• Design Tokens: System-level (single version for all tokens)
• Components: Start system-level, migrate to component-level at scale (>50 components)
• DCS: Synchronized with token version

Branching Strategy

Unified Philosophy: Mirror Git branching in design tools

Branch Types:

• main: Production-ready (protected)
• feature/DS-XXX-description: Isolated development
• hotfix/fix-name: Critical bug fixes
• experiment/exploration-name: R&D that may not ship

Correlation Pattern:

Git: feature/DS-123-button-variants
Figma: web/DS-123/button-variants/2026-05
Penpot: feature-button-variants (file or branch)

Linked via: Ticket DS-123, PR description

Figma Branching:

• Native branching (Organization tier)
• Create from main → Develop → Update from main → Merge
• Conflict resolution: Side-by-side, choose version (all-or-nothing)
• Best practice: Short-lived (1-2 weeks), granular scope

Penpot Workarounds (native branching not yet available):

• File duplication with "[Branch] feature-name"
• Version history for solo work
• Separate projects for long-running experiments

Release Management

Release Pipeline:

Design Change → Token Update → Library Build → Package Publish → Staging → Production

Stages:

1. Preparation: Code freeze, final testing, prepare changelog
2. Design Library Publish: Figma/Penpot library published
3. Token Build: Style Dictionary compiles
4. Component Build: TypeScript compilation, bundling
5. Package Publish: npm publish, Git tag
6. Documentation Deploy: Storybook, release notes
7. Staged Rollout: Alpha (DS team) → Beta (volunteers) → General (all teams)
8. Post-Release: Monitor errors, gather feedback, track adoption

Rollback Procedure (P0/P1 incidents):

# Deprecate bad version
npm deprecate @company/[email protected] "Critical bug. Use 2.5.0"
npm dist-tag add @company/[email protected] latest

# Or publish emergency revert
git revert [bad-commit]
npm version patch
npm publish

Deprecation and Migration

Three-Phase Approach (6-12 months):

Phase 1: Warn (6 months)

• Add deprecation notices, console warnings
• Document replacement
• Provide migration guide

Phase 2: Wait (3-6 months)

• Monitor usage (<10% goal before removal)
• Direct outreach to high-usage teams
• Provide codemods

Phase 3: Remove (MAJOR release)

• Delete deprecated code
• Keep migration guide in docs

Communication Cadence:

• Deprecation announcement (release notes, email, Slack)
• Monthly reminders during wait phase
• Final warning 1 month before removal

Audit Trails and Governance

Audit System:

what_to_track:
  - Design changes (Figma/Penpot webhooks)
  - Code changes (Git commits)
  - Sync events (DCS pipeline logs)
  - Usage analytics (component telemetry)

storage:
  - Hot (90 days): PostgreSQL
  - Warm (1 year): S3 compressed
  - Cold (7 years): Glacier

metrics:
  - Component health (active, deprecated, unused)
  - Token health (total, unused, violations)
  - Adoption (products using DS, version distribution)
  - Quality (a11y score, regression pass rate)

---

SECTION 8 — OPERATIONAL RUNBOOK

Day-1 Setup Checklist

Estimated Time: 4-8 hours

Phase 1: Repository Setup (30 min)

mkdir design-system && cd design-system
git init

# Directory structure
mkdir -p {tokens,packages/ui-components/src,apps/docs,dcs,scripts}

# Initialize workspaces
npm init -w packages/ui-components
npm init -w packages/design-tokens

Phase 2: Penpot Local Deployment (20 min)

mkdir penpot-local && cd penpot-local
wget https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml
# Configure environment variables
docker compose up -d
# Access: http://localhost:9001

Phase 3: Token Pipeline Setup (45 min)

// tokens/tokens.json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "color": {
    "base": {
      "$type": "color",
      "blue-500": { "$value": "#0066cc" }
    },
    "semantic": {
      "$type": "color",
      "primary": { "$value": "{color.base.blue-500}" }
    }
  }
}

// packages/design-tokens/sd.config.js
export default {
  source: ['../../tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'design-tokens.css',
        format: 'css/variables'
      }]
    }
  }
};

Phase 4: DCS Initialization (30 min)

// dcs/dcs.json
{
  "version": "1.0.0",
  "tokens": { "version": "1.0.0", "source": "../tokens/tokens.json" },
  "components": [],
  "patterns": []
}

Phase 5: CI/CD Pipeline (45 min)

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run tokens:build
      - run: npm test

Phase 6: Documentation Site (30 min)

npx storybook@latest init
npm run storybook
# Access: http://localhost:6006

Validation Checklist:

• [ ] Penpot running at localhost:9001
• [ ] Tokens building successfully
• [ ] Storybook running at localhost:6006
• [ ] CI/CD pipeline passing
• [ ] First component in Storybook

Day-2 Operations

Token Update Workflow:

1. Designer updates in Penpot/Figma
2. Export to tokens/tokens.json
3. Validate: npm run tokens:validate
4. Build: npm run tokens:build
5. Update DCS with change metadata
6. Create PR with visual regression
7. Merge and publish PATCH version

Component Addition Workflow:

1. Design in Penpot (2-3 days)
2. Export component metadata to DCS
3. Create Git branch: feature/DS-301-datatable
4. Implement component code (3-5 days)
5. Create Storybook stories
6. Write tests (unit, a11y, visual)
7. Validation gates (visual ≥95%, WCAG AA, coverage 100%)
8. Code review and merge
9. Release MINOR version

Breaking Change Workflow (MAJOR):

1. RFC proposal with governance approval
2. Deprecation release (MINOR) - both old and new work
3. 6-month communication campaign
4. Codemod creation for automatic migration
5. Monthly reminders, usage tracking
6. Removal release (MAJOR)
7. Post-release monitoring

Incident Response

Severity Levels:

• P0 Critical: Production outage, A11y regression, security vulnerability (1 hour response)
• P1 High: Major functionality broken, blocking teams (4 hour response)
• P2 Medium: Minor issues, workaround available (1 day response)
• P3 Low: Visual inconsistencies, docs (next sprint)

Rollback Procedure:

1. Assess impact (5-15 min)
2. Decide rollback vs. hotfix
3. Execute rollback (npm, Figma, Penpot)
4. Communicate urgently (Slack, email, status page)
5. Hotfix release within 4 hours
6. Post-mortem within 48 hours

Conflict Escalation:

1. Automated conflict report generated
2. Notify component owner, designer, tech lead
3. Sync meeting scheduled
4. Decision documented with rationale
5. Resolution applied and DCS updated

Maintenance

Penpot Upgrade:

1. Review release notes
2. Backup (database, assets, config)
3. Test in staging
4. Announce maintenance window
5. Stop services, update docker-compose
6. Pull new images, run migrations
7. Verify and test
8. Rollback if needed

Plugin Updates:

• Check plugin API changes
• Update plugin code and manifest
• Test in updated Penpot
• Deploy to hosting

DCS Schema Migration:

• Version bump (MAJOR if breaking)
• Create migration script
• Update validation schema
• Update all agents
• Test and deploy

---

CONCLUSION

This Design Intent Ownership Bible 2.0 provides a complete, production-ready methodology for managing design systems with Penpot-primary architecture, Figma compatibility, and Canva Pro marketing integration. Key achievements:

✅ Endpoint-agnostic Penpot deployment - Works across local Docker, VPS, Kubernetes, AWS ✅ True bi-directional sync - Design ↔ Code with conflict resolution via DCS ✅ Equal-depth hosting coverage - SSGs, Headless CMS, WordPress all fully documented ✅ AI agent orchestration - Multi-specialist pattern with MCP integration ✅ Complete lifecycle management - Versioning, branching, releases, deprecation ✅ Operational excellence - Day-1 setup through day-2 maintenance

Next Steps:

1. Bootstrap infrastructure using Day-1 checklist
2. Create first 5 core components
3. Set up visual regression testing
4. Deploy documentation site
5. Begin production adoption

The methodology is grassroots-accessible yet enterprise-ready, balancing technical rigor with practical implementation guidance. Save this document as your authoritative reference for design intent ownership at scale.

Version: 2.0 (May 2026) License: Proprietary - Internal Use Only Maintained By: Design System Team