--gl-text-color-disabled fails text-contrast, so if content/context need to be visually perceivable then it should not be disabled.

Guidance we had at Splunk UI

Dimmed: Rendering a 'dimmed' Menu Item ensures the Menu Item is still discoverable and can receive focus, but the Menu Item cannot not be activated by the user.

Disabled: Consider using a 'dimmed' Menu Item. Disabling Menu Items creates barriers for all users and can exclude people with disabilities.

Current State

The GlDropdownItem component does not have a dimmed prop. It currently supports:

• isChecked / isCheckItem for check states
• disabled (inherited from Bootstrap Vue via $attrs)
• Icons, avatars, and secondary text

Disabled removes the element from the a11y tree and would not be available to screen-readers, so any help text or tooltip content is lost.

Recommendation

Add dimmed menu item functionality:

1. Add a dimmed prop to GlDropdownItem that applies a CSS class for visual styling (reduced opacity, grayed out)
2. Prevent activation by adding a click handler that stops propagation when dimmed
3. Keep it focusable by not using the disabled attribute (which removes from tab order)
4. Add corresponding SCSS to style dimmed items appropriately

[Decision]

Based on this two day exploration I do not recommend we look to implement and maintain a Figma Make template, unless there's enough demand across GitLab for Make vs other rapid prototyping options

Day 2 update — validation complete:

Overall: 3 out of 4 validated. The workflow is viable.

Picked up from Day 1's finding that the guideline-based workflow was viable but token fidelity was the remaining gap. Here's where each question landed:

✅ Importing @gitlab/ui Works as a reference package. Make reads the source to understand component APIs, SCSS implementation, and design decisions.

✅ Design tokens Works @gitlab/ui ships its compiled token CSS as part of the npm package and Vite can import it directly:

@import '@gitlab/ui/src/tokens/build/css/tokens.css';

All --gl-* custom properties are live in Make and stay in sync automatically when @gitlab/ui is upgraded. No separate file to maintain.

✅ Vue → React with caveats) The guideline approach from Day 1 holds up. button.md was generated with Claude using @gitlab/ui source and Pajamas docs as context, then validated and refined over two days in Make. Auditing against the real SCSS source and live Pajamas docs caught several spec gaps — border radius, font weight, icon size, selected state color. All corrected. Added a global rule to Guidelines.md enforcing var(--gl-*) token usage on every component Make generates going forward.

❌ Fonts (Make sandbox limitation, not a GitLab one) GitLab Sans is publicly available at https://gitlab-org.gitlab.io/frontend/fonts/ and the @gitlab/fonts npm package is installable. The issue is Figma Make's preview sandbox — it blocks external network requests, so @font-face rules pointing to the canonical URL never load. This is a Make environment constraint worth raising directly with Figma. The fix is on their end, not ours.

The core problem is Vue → React and it doesn't go away.

1. Request Vue support in Figma Make The real fix. Eliminates the translation layer entirely. Worth raising directly with Figma as a design system use case, GitLab is likely not the only company in this position.

2. CI-coupled guideline maintenance A script that regenerates component.md files from @gitlab/ui source on each release, with a CI process that flags stale guidelines when component source changes. The most realistic near-term option but requires dedicated ownership to stay healthy.

3. @gitlab/ui-react wrapper package A proper React implementation of Pajamas components that Make could import directly, the same way it handles shadcn today. Every component would have the same prop API as @gitlab/ui and use the same --gl-* token chain we validated this week — meaning color, spacing, and typography changes flow through automatically. What's left to maintain manually is structural and behavioral changes, which are less frequent but more expensive to translate.

The maintenance cost is real and every component change in the Vue library needs a corresponding change in the React library. It's a parallel implementation to maintain indefinitely. It only makes sense if there's enough demand across GitLab for Make, other React-based tooling, third-party integrations to justify the investment. If that demand exists, it's the most durable path. If it doesn't, it's the same maintenance cost as today with more formality around it.

Day 1

Figma make template - Test

button.md

guidelines.md

GlButton.css

GlButton.tsx

Did some initial exploration on this. Since Make only supports React and @gitlab/ui is Vue, direct package import isn't an option — but I found a viable workflow:

1. Install @gitlab/ui as a reference-only package in Make (readable source, no Vue imports)
2. Provide one guideline markdown file per component that teaches Make how to build a React equivalent
3. Auto-generate those guideline files using Claude Code from the Pajamas docs page, @gitlab/ui source, and design tokens

Tested end-to-end with Button. From a clean Make file with just a Guidelines.md and a generated button.md, Make produced a standalone GlButton — no shadcn dependency, correct prop API, contextual design tokens (--gl-button-*) with hex fallbacks, and proper a11y (double focus ring, aria-disabled loading, aria-pressed toggle). Side-by-side visual comparison against the docs caught remaining color issues in the category model that still need correction.

Removed "project" from the screen-reader text as it didn't make sense to keep for the contexts where you are not at the project level.

• Update recording.

💡 Some additional content could be:

• Accessibility We touch on a11y fixes when they appear in the gitlab-ui changelog, but there's no dedicated section for it.
• Community contributions Callout for non-DS team members who contributed to Pajamas that month.
• Cool stuff / on our radar Experimental work, explorations, interesting problems the team is thinking about.
• External inspiration or resources Design system news, relevant articles, tooling updates from the broader DS community.
• Team happenings New team members, departures, role changes, shoutouts for contributions.

Summary

Create a repeatable, low-effort content template that aggregates Pajamas Design System changes into a centralized digest distributed via The Loop on a monthly cadence for ICs, and a quarterly rollup for design/engineering leadership and C-suite.

This addresses a clear gap: there is no single place for consumers to go to understand what shipped, what changed in their Figma files, and what changed in code. Changes are currently scattered across three sources (UI Kit release notes, gitlab-ui changelog, design.gitlab.com changelog) with no curation layer on top.

pajamas-loop-pilot.md

pajamas-loop-template.md

pajamas-quarterly-template.md

Problem

• No single source of change or impact
• "Pajamas" and "gitlab-ui" are used interchangeably the relationship between the system and its layers is could be unclear
• Breaking changes, deprecations, and removals can go unnoticed unless consumers are actively watching changelogs

Goals

• Publish a monthly IC digest via The Loop that curates signal from all three sources
• Publish a quarterly leadership rollup via The Loop that tells the impact story across the three monthly issues
• Keep curation effort to ~45 min/month for the monthly, ~60 min/quarter for the rollup
• Establish a rotating curation model so no single person owns this indefinitely
• Over time, use the adoption signals section of the quarterly to build toward measurable DS health metrics

Non-goals

• This is not a replacement for the existing release notes pages those remain the full source of truth
• This is not a new tool or platform, The Loop is the distribution channel (for now)
• We are not automating curation (yet) — this is a human process to start

Content sources

Audience

Monthly digest structure

Each issue covers one milestone and includes:

1. UI Kit (Figma) — Breaking changes · Deprecations · Removals · New · Enhancements · Bug fixes
2. gitlab-ui (coded components) — Breaking changes · Deprecations · Removals · New · Enhancements · Bug fixes
3. Docs — Only when something changes what consumers should know or do
4. Coming up — 1–2 things in flight for next milestone

Curation rules:

• Skip all deps: entries in changelogs — automated Renovate bumps, zero consumer impact
• Lead every section with breaking changes and deprecations
• Deprecation = still present, migrate away; Removal = gone, act now
• Docs changelog: only include if it changes consumer behavior, not restructures

Quarterly rollup structure

Derived from the three monthly issues. Sections in priority order:

1. Impact this quarter — What did Pajamas shipping enable for product teams? (2–3 sentences, outcomes not output)
2. Adoption signals — Qualitative or quantitative signals that consumers are finding and trusting Pajamas
3. What shipped — themes — 2–4 narrative themes across the quarter, not a list of changes
4. What's next — 2–3 initiatives framed around impact, not tasks
5. Team health (optional) — Capacity or resourcing flags for leadership

Delivery plan

Phase 1 — Pilot (this milestone)

• Finalize monthly digest template
• Finalize quarterly rollup template
• Curate and publish first issue via The Loop
• Note the Pajamas / gitlab-ui naming distinction in the pilot issue orientation block

Phase 2 — Establish cadence

• Identify first rotation of curators
• Document curation process (source → template mapping, time estimate, what to skip)
• Confirm publish timing relative to milestone close

Phase 3 — Quarterly rollup

• Publish first quarterly rollup at end of Q
• Identify 1–2 adoption signals to begin tracking for Q2 rollup

Phase 4 — Iterate

• Collect feedback from IC readers after issue 2
• Collect feedback from leadership after first quarterly
• Adjust template and scope based on signal

Open questions

• Who is the DRI for the pilot issue?
• What is the publish timing — end of milestone, or a fixed date each month?
• What adoption signals can we start tracking now for the Q2 quarterly?
• Should the quarterly rollup eventually move to a different format (doc, slide) as the audience grows?

Automation — Level 1

⚠️ GAI was used to create this draft automation outline

MonthlyDigestIssueTemplate.md

pajamas-digest-pipeline.txt

pajamas-digest-script.js

A scheduled CI pipeline runs on the last day of each milestone. It fetches and filters content from the gitlab-ui changelog and UI Kit release notes, then creates a pre-populated draft GitLab issue assigned to the curator DRI. The curator does one editorial pass (~15 min) and sends to The Loop.

What the pipeline does:

• Fetches the gitlab-ui changelog via the GitLab API
• Strips all deps: entries (Renovate bumps, zero consumer impact)
• Groups remaining entries by BREAKING CHANGES, feat:, and fix:
• Fetches the latest UI Kit release notes from design.gitlab.com
• Creates a new issue in this project using the monthly digest issue template (see below)
• Assigns to the curator DRI, applies label comms::draft

What the curator still does:

• Rewrites raw changelog entries into plain language
• Adds the "Coming up" section (requires roadmap visibility)
• Removes any docs changelog noise that slipped through
• Changes label from comms::draft to comms::ready when done

Future levels:

• Level 2: Add AI summarization via Claude API to generate first-draft narrative sentences per section (~3–5 days additional effort)
• Level 3: Slack bot notification to #g_pajamas-design-system on draft creation + quarterly auto-generation from three monthly issues (~1–2 weeks additional effort)

How to set this up

⚠️ The draft script and pipeline config are directionally correct but should be treated as a conversation starter with ENG, not a ready-to-ship PR. Use them to align on approach before implementation.

Prerequisites:

• Access to the DS GitLab project with Maintainer role or above
• A project or personal access token with api scope
• Node.js available in CI (or confirm correct runner image with ENG)

Steps:

1. Add digest.js to the root of the DS repo
2. Add the generate-monthly-digest job to the existing .gitlab-ci.yml
3. Go to Settings → CI/CD → Variables and add:
   • GITLAB_TOKEN — access token with api scope
   • GITLAB_PROJECT_ID — numeric ID of this project
   • CURATOR_USERNAME — GitLab username to assign the draft issue to
4. Go to CI/CD → Schedules and create a new schedule aligned to milestone close date
5. Trigger manually once to verify the issue is created correctly before relying on the schedule

Questions to validate with ENG before implementing:

• Is the gitlab-ui changelog accessible via the GitLab API as the script assumes, or does it require different auth/path?
  • Will the HTML parsing of the UI Kit release notes page hold up, or do we need a more robust approach?
  • What is the exact milestone close date to set the cron correctly?
  • Is node:20-alpine the right runner image, or does CI use a different environment?
  • Should CURATOR_USERNAME be static or pulled dynamically from a rotation list?

Adam Ferch (0d1da5b7) at 27 Feb 19:05

Adam Ferch (ba2d24c2) at 27 Feb 16:07

Adam Ferch (1ab6f0e0) at 26 Feb 23:24

Supplementing the existing link text felt like the right move rather than going down the heading route the issue caught. A Small fix that didn't require design and adds clear context to the link and page.

In the future we could look to include the author and time stamp additionally so you'd get something like: [commit string] most recent commit in this project authored by [name] [time-stamp]