Pine MCP

Teaching AI to build with the design system.

Pine MCP gives AI assistants direct access to Pine's component contracts, accessibility guidance, token rules, layout patterns, and implementation standards. Instead of relying on generic training data, generated code can use the same source of truth as the engineers maintaining the system.

Pine MCP moves design-system decisions from review time to generation time.

Overview

Structured context turns Pine from something AI can mention into something AI can follow.

Pine MCP is not simply documentation exposed to an AI assistant. It is structured design-system context that helps AI choose the correct components, tokens, layouts, accessibility patterns, and implementation rules before code reaches review.

Core argument

A generic model predicts the most common answer on the public web. Pine MCP retrieves the answer supported by the current design system.

Problem

Generic AI output often looked reasonable while violating local system rules.

Generic AI assistants produce plausible UI based on common public patterns: raw HTML, utility classes, Bootstrap-like grids, hardcoded values, and component APIs from other systems. The problem was not that generated code always looked obviously broken. It often looked acceptable in isolation.

The most dangerous output was not obviously incorrect. It was code that looked acceptable in isolation but violated the system in ways that surfaced later through accessibility issues, dark-mode failures, inconsistent behavior, or code review.

  • Incorrect component selection
  • Missing accessibility relationships
  • Raw layout primitives instead of Pine layout components
  • Core color tokens where semantic tokens were required
  • Component APIs that did not match Pine

Documentation Was Not Enough

Documentation tells. Structured context guides. Validation checks.

Human documentation is written for browsing, learning, and judgment. AI-assisted development needs retrievable context that is current, specific, and available at the moment code is being generated.

Traditional documentation

  • Written for browsing and learning
  • Requires the reader to find the relevant page
  • Leaves implementation choices to the developer
  • Usually catches mistakes during review

Pine MCP

  • Retrieves the relevant component contract or rule
  • Supplies current, system-specific context at generation time
  • Reduces ambiguous implementation choices
  • Supports validation before code reaches review

How Pine MCP Works

MCP tools retrieve the system rule when the assistant needs it.

Pine MCP makes design-system knowledge available as structured context. Tools can retrieve component APIs, design guidance, layout rules, token expectations, and accessibility guidance during generation rather than after a pull request is opened.

  • get_pine_component
  • get_pine_design_doc
Pine MCP generation flowMCP tools retrieve current component APIs and design guidance at the moment the AI assistant needs them.
  1. Developer request
  2. AI assistant
  3. Pine MCP tools
  4. Component contracts and design guidance
  5. Generated implementation
  6. Validation

Evidence

Generic output versus Pine-guided output.

These examples show the kinds of decisions Pine MCP can pull forward: semantic tokens, layout primitives, accessible names, feedback behavior, and form accessibility.

Request

Semantic tokens and dark mode

Style a card with a white background, thin gray border, dark title text, and slightly lighter body text.

Likely generic output

.card {
  background-color: var(--pine-color-white);
  border: 1px solid var(--pine-color-grey-300);
  color: var(--pine-color-grey-900);

  .card-body {
    color: var(--pine-color-grey-700);
  }
}

Pine-compliant output

.card {
  background-color: var(--pine-color-background-container);
  border: 1px solid var(--pine-color-border);
  color: var(--pine-color-text);

  .card-body {
    color: var(--pine-color-text-muted);
  }
}
Rule enforced
Use semantic tokens for contextual meaning. Do not use hardcoded colors or fixed core color tokens where semantic alternatives exist.
Why it matters
Both versions may look identical in light mode, but only the semantic-token version adapts correctly to dark mode.
Request

Responsive layout

Build a two-column page with wide main content and a narrow sidebar. Stack it on mobile.

Likely generic output

<div style="max-width: 1200px; margin: 0 auto;">
  <div style="display: flex; gap: 16px;">
    <div style="flex: 2;">Main content</div>
    <div style="flex: 1;">Sidebar</div>
  </div>
</div>

Pine-compliant output

<pds-container size="lg">
  <pds-row col-gap="md">
    <pds-box size-xs="12" size-md="8">
      Main content
    </pds-box>
    <pds-box size-xs="12" size-md="4">
      Sidebar
    </pds-box>
  </pds-row>
</pds-container>
Rule enforced
Use container, row, and box with mobile-first breakpoint sizing. Do not introduce inline styles or a competing layout model.
Why it matters
The Pine version uses the system's actual responsive architecture instead of creating another layout pattern for teams to maintain.
Request

Accessible icon-only close button

Add a close button to the modal header that just shows an X icon.

Likely generic output

<button class="modal-close" onclick="close()">
  <svg width="16" height="16">
    <!-- X icon path -->
  </svg>
</button>

Pine-compliant output

<pds-button icon-only aria-label="Close dialog">
  <pds-icon slot="start" name="remove" aria-hidden="true"></pds-icon>
  Close dialog
</pds-button>
Rule enforced
Icon-only controls require an accessible name, and decorative icons must be hidden from assistive technology.
Why it matters
The generic version may be announced only as button. The Pine-guided version communicates Close dialog button.
More examples

Toast versus alert

Request: Show a success message after the user clicks Save.

Generic output
{saved && (
  <div className="bg-green-100 text-green-800 p-3">
    Saved!
  </div>
)}
Pine-compliant output
<pds-toast
  component-id="save-success"
  variant="success"
  message="Profile saved."
></pds-toast>
Rule enforced
Use toast for temporary feedback about a completed action that does not require acknowledgment. Use alert for persistent or critical information.
Why it matters
The system encodes behavior and hierarchy, not just color.

Accessible form field

Request: Add an email signup form with an email input and submit button.

Generic output
<input type="email" placeholder="Enter your email" />
<button type="submit">Submit</button>
Pine-compliant output
<pds-input
  component-id="signup-email"
  label="Email"
  type="email"
  name="email"
  required
></pds-input>

<pds-button variant="primary" type="submit">
  Submit
</pds-button>
Rule enforced
Inputs require persistent labels. Placeholder text is not a label. Use the system component API so error state and accessibility relationships remain intact.
Why it matters
The system makes accessible implementation the default rather than something each developer must rebuild.

Pattern

Pine MCP collapses plausible choices into the system-supported choice.

Across the examples, the pattern is consistent. The assistant should not have to infer Pine from generic web examples. It should retrieve the current rule, apply the documented component contract, and avoid anti-patterns before a reviewer has to correct them.

  • Accessible names for icon-only controls
  • Toast versus alert based on behavioral purpose
  • System layout primitives instead of generic CSS
  • Semantic tokens instead of fixed color values
  • Persistent labels and system-managed form accessibility

Generation-Time Guidance

Pine MCP does not remove human review. It changes what review is for.

The old flow pushed recurring system corrections into review. The Pine MCP flow moves those corrections earlier so reviewers can spend more attention on product judgment, edge cases, and user experience.

Review-time correction

  1. Generate
  2. Implement
  3. Review
  4. Find violations
  5. Revise

Generation-time guidance

  1. Retrieve rules
  2. Generate within constraints
  3. Validate
  4. Review higher-level decisions
Core conclusion

Pine MCP does not remove human review. It moves repetitive system corrections earlier so reviewers can focus on product judgment, edge cases, and user experience.

Observed Workflow Outcomes

The value is qualitative, but concrete.

I am not presenting adoption numbers or measured business impact here. The defensible outcome is a clearer workflow: system-specific decisions become available inside AI-assisted development instead of appearing only as review feedback.

  • More consistent component selection
  • Better token usage
  • Accessibility guidance available during implementation
  • Reduced reliance on generic web patterns
  • Design-system decisions available within AI-assisted workflows
  • Repetitive corrections moved earlier in the development process

What I Learned

AI-assisted workflows make the design system contract more explicit.

  • AI is a new consumer of the design system.
  • Human-readable documentation and machine-usable context are related, but not identical.
  • The system needs explicit component contracts, priorities, constraints, and anti-patterns.
  • Validation is as important as retrieval.
  • The most valuable guardrails address subtle errors that still look visually plausible.

Related Work

This work connects Pine, governance, and theme infrastructure.

Pine Design SystemInfluence Through SystemsKajabi Admin Dark Mode
View Pine Design SystemBack to workTalk design systems and AI