6.fCSS / design system doctrine

1. The four doctrines

The CSS layer of the SDK is governed by four doctrines, each pinned earlier in the Step 6 thread, consolidated here for reference.

2. What the SDK ships

Total CSS shipped per app: ~11KB minified, ~3KB gzipped. App pages add four <link> tags (tokens + components + utilities + Font Awesome kit) and consume from there.

3. The class facade pattern in practice

What the SDK ships

/* sdk/v1.0/components.css */
.pc-btn-primary-v1 {
  background: var(--pc-accent-orange);
  height: 44px;
  border-radius: 3px;
}

/* The facade — mirrors the SDK's "current" variant.
   At v1.0 there's only v1, so it equals v1. */
.pc-btn-primary {
  background: var(--pc-accent-orange);
  height: 44px;
  border-radius: 3px;
}

What the SDK ships at v1.3 (after two design evolutions)

/* sdk/v1.3/components.css */
.pc-btn-primary-v1 {  /* UNCHANGED from v1.0 — Lotus Notes durability */
  background: var(--pc-accent-orange);
  height: 44px;
  border-radius: 3px;
}

.pc-btn-primary-v2 {  /* added in v1.1 — NEVER edited again */
  background: var(--pc-accent-orange);
  height: 48px;
  border-radius: 6px;
  font-weight: 600;
}

.pc-btn-primary-v3 {  /* added in v1.3 — current */
  background: var(--pc-accent-orange);
  height: 48px;
  border-radius: 8px;
  font-weight: 600;
  box-shadow: 0 1px 2px rgba(0,0,0,0.08);
}

/* Facade now mirrors v3 */
.pc-btn-primary {
  background: var(--pc-accent-orange);
  height: 48px;
  border-radius: 8px;
  font-weight: 600;
  box-shadow: 0 1px 2px rgba(0,0,0,0.08);
}

What vibe apps consume

Most apps use the facade. Apps with strict visual contracts (customer-facing brand-book commitments) pin to versioned classes.

4. The npm semver mapping

Updates ripple at app re-deployment, not continuously — the Terraform apply is the equivalent of npm install. The SDK file in each app's S3 bucket is the lockfile.

5. App.css — the narrow escape valve

When a vibe app needs visual customization that doesn't fit the SDK's defaults, it consumes a per-app stylesheet at cartridges/<dept>/<app>/app.css.

Example app.css for the chatbot:

/* cartridges/engineering/chatbot/app.css */

/* Layout: thread list on left, message pane on right */
body.pc-app-chatbot main {
  display: grid;
  grid-template-columns: 280px 1fr;
  gap: 0;
}

/* Minor theme override: slightly softer chat bubble background */
body.pc-app-chatbot {
  --pc-chat-bubble-bg: #f0f9ff;
}

That's it. The chatbot's app.css contains only layout that's structurally specific to the chatbot and one custom property override. No new components; no overrides of platform classes outside the body scope.

6. The promotion / demotion flow

App Review PR template — CSS section

## CSS / design changes

Pick one:
- [ ] No new CSS introduced — app consumes existing SDK classes only.
- [ ] New SDK promotion proposed (UI team review required).
- [ ] App-local additions in app.css only (UI team review still required, just for boundary check).

If proposing SDK promotion:
| Proposed class             | Component purpose                       | Reusability rationale                                           |
|----------------------------|-----------------------------------------|-----------------------------------------------------------------|
| .pc-streaming-message-v1   | Animated typing chatbot bubble          | Every future chat/assistant vibe app will need this             |
| .pc-chat-bubble-v1         | User/assistant chat message container   | Chat shape is structurally similar across vibe apps             |

UI team reviewer checklist:
- [ ] Does this fit the platform's visual vocabulary?
- [ ] Is this likely to be needed by future vibe apps?
- [ ] Is the class naming aligned with existing patterns (.pc-{component}-v{N})?
- [ ] Does it work with existing design tokens, or does it require new ones?
- [ ] Decision: PROMOTE / KEEP APP-LOCAL / REJECT

7. Failure modes — what the doctrine catches

8. Why this doctrine matters operationally