Ambient UI Development workflow

Strict workflow execution to be used when performing any ambient-ui component work.

User Input

$ARGUMENTS

Workflow

1. Align with Specs

All work must be aligned with specs. If the user or instructions are asking for work to be done without a verified matching section in a spec, STOP.

Before proceeding with implementation, update the relevant spec to match the request.

2. Perform Test Driven Development

Determine the size of the work. If it is large, break it down into smaller atomic units of work and execute this workflow for each one. You can use subagents to handle this gracefully, preserving your context.

Define tests that are relevant and that, when they pass, provide a genuine trust that the system is properly implemented in a way that aligns with the spec and the user's intent.

Then, proceed with methodical implementation, breaking work into atomic units of work for subagents when possible. Bias towards using subagents for implementation tasks, but ensure they read this workflow skill to understand the development standards.

Test and verify implementation before proceeding to the next step.

Standards

These standards are to be used during all ambient-ui component development work.

Fakes over Mocks

When testing, fakes are to be preferred over mocks. Tests that don't test reality are not tests at all.

Accessibility

• For Red Hat assets, small text (17pt or smaller) needs to have a 4.5:1 contrast ratio at minimum. Large text (18pt or larger) and informative graphics like icons need to have a 3:1 contrast ratio at minimum.

• Saturated hues that are similar in intensity can vibrate when used together, creating fuzziness around the edges like a glowing blur. These colors can be difficult for anyone to look at and distinguish, and even painful for those with vision differences. An example of high-contrast colors that do not vibrate.

  Do this: Combine bright colors with less saturated and neutral colors. Image showing misuse: An example of low-contrast colors that vibrate.

  Not this: Don’t use colors with similar intensity in the same area.

Technology

• React/Next.js
• shadcn/ui components
• Tabbed views MUST persist the active tab in the URL via ?tab= query parameter using controlled <Tabs value={activeTab}> with useState + useEffect + replaceState. Ensures tabs survive reload and support deep linking.

Colors

Core Palette

Secondary Palette

Note: The "Auxiliary colors" section in your text was empty, so it has been omitted here.

Information Palette

⚠️ Usage Note: These colors are utilitarian. They should only be used for their intended purposes, not for decorative visuals.

Color Association More info red Red Hat Red is our brand color. Do not use red to represent negative things. danger-orange Error, decrease, or failure Something negative has occurred, like a destructive error or a decrease in value. orange Caution A non-destructive action or error has occurred. yellow Warning Take action now to avoid a destructive action or error. success-green Success, increase Something positive has occurred, like a successful action or increase in value. teal General or neutral A button or information has no severity. interaction-blue Link or interaction Clicking the object or text leads to a hyperlink or state change. purple Info or note tip Helpful information is available. gray Null A button or information is unavailable or unimportant.

Typefaces

Red Hat Text takes all of the personality from Display and optimizes it for more demanding applications. As the name implies, it’s easier to read in paragraphs or when text is used at small sizes—like in a whitepaper or tooltip.

To increase readability, Text has more height difference between the upper- and lowercase letters, more space between narrow characters, and more variation in letterform stroke weights.

Red Hat Mono

Red Hat Mono was created to distinguish code from natural-language text. Mono stands for monospaced, meaning each letter takes up the same amount of horizontal space. This creates neat columns of text and makes scanning code easier.

Mono should only be used when demonstrating code snippets in communications and interfaces, or as a stylistic approach for a more technical audience like the Red Hat Developer Program or the Code Comments podcast.

General Principles

• Use consistent design tokens
• Use iconography to improve the user experience and ability to scan the page
• Everything must be accessible
• Use reusable components
• Unless specified by the user, NEVER MAKE CONSIDERATIONS BASED ON A NEED FOR BACKWARDS COMPATIBILITY.
• Use atomic, conventional commits.

3. Perform Critical Review

Launch the following agents in parallel to review and critique your work:

1. Security review agent:

• Expert in OWASP vulnerability classes
• Thoroughly vets for supply chain vulnerabilities

2. Spec alignment review agent:

• Thoroughly review the relevant spec & the implementation. Flags any gaps, no matter how trivial. Spec is the source of truth.

3. Architecture review agent:

• Identifies architectural inconsistencies, deviations from standards (domain driven design, domain oriented observability, using ports/adapters, etc.)
• Identifies duplicate code, magic strings/numbers, etc.

4. Code quality agent:

• Identify lint & formatting issues
• Identify dead code

5. Documentation sync agent:

• Ensure relevant README & documentation reflects the changes in this unit of work
• Do not be overly verbose. Follow any project documentation guidelines, aim for conciseness. Do not over document.

6. UX review agent:

• Embodies the persona of Steve Krug and the book "Don't Make Me Think"
• Identifies anything that might make the user think, is poorly organized, doesn't follow principles, etc.
• Uses playwright to see and interact with the ui to verify & discover all findings.

7. User target demographic review agent:

• Embodies the persona of an engineer that is using the platform to:
  • Observe units of work, their status, and the overall status of the system (is human intervention necessary etc.)
  • Define and maintain credentials, binding access to projects and specific agents.
• Exercises the application from end to end, following real user patterns to discover system breaking bugs.

4. Address Review Comments

Use subagent(s) to address relevant review comments. Although you are to use your judgement about whether a review comment is relevant, you are also to be picky about your work. Take pride in doing the correct thing, even if it's not the easiest.

After addressing review comments, loop back to step 3.

If step 3 provides no actionable comments, proceed to the next step. Do not worry if you spend many cycles in this stage. Correctness is worth the effort.

5. Request User Feedback

Get the UI in a running state so that the user can provide feedback. There are two ways for you to do this:

Running inside ambient

If you are running within the ambient platform, you will have instructions for building images, and deploying to an OpenShift cluster. You should do this, create a route, and add the route to the relevant annotation (see your operating instructions.)

Running locally

If you are running locally, simply follow the local development setup, and provide the user with the URL to open in their browser to provide feedback. Let them know what to test and where to look.