Update the style guide (md)

[savindi7]

Purpose

$subject

Related Issues

• N/A

Related PRs

• N/A

Checklist

• e2e cypress tests locally verified. (for internal contributers)
• Manual test round performed and verified.
• UX/UI review done on the final implementation.
• Documentation provided. (Add links if there are any)
• Relevant backend changes deployed and verified
• Unit tests provided. (Add links if there are any)
• Integration tests provided. (Add links if there are any)

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines
• Ran FindSecurityBugs plugin and verified report
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets

Developer Checklist (Mandatory)

• Complete the Developer Checklist in the related product-is issue to track any behavioral change or migration impact.

Summary by CodeRabbit

• Documentation
  • Redesigned style guide with comprehensive sections on styling architecture, component guidelines, theme configuration, and migration strategy for improved developer reference and consistency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The STYLE-GUIDE.md document was completely restructured, replacing the previous WSO2 Identity Apps Style Guide with a comprehensive, modular guide covering styling architecture, component guidelines, UI system integration, theme customization, and migration strategy. The new guide establishes a two-library system (Oxygen UI primary and Semantic UI React legacy) with practical examples and clear upgrade pathways.

Changes

Cohort / File(s)

Summary

Style Guide Redesign docs/STYLE-GUIDE.md

Comprehensive rewrite replacing legacy guide with modular structure covering: Styling Architecture, Component Guidelines (with prop naming conventions and TS documentation), Oxygen UI integration patterns, theme/color customization via Extended Theme, tree-shaking optimization through per-component imports, and detailed Migration Strategy with component mapping and checklist. Added layered component hierarchy (Pages > Features > Compositions > Base Components), extraction/pruning rules, and practical code examples. Removed legacy Introduction and Form Library sections.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A guide so fresh, now refined and bright,
From chaos old to structure right,
Oxygen shines, theme-colors gleam,
Components stack in layered dream,
Migration paths light up the way—
Hooray, hooray, styling's here to stay! 🎨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description uses a placeholder variable ($subject) instead of actual content, making it incomplete and not providing meaningful information about the extensive style guide updates.	Replace the $subject placeholder with a detailed description of the style guide changes, including the shift to Oxygen UI, new component guidelines, and migration strategy.
Title check	❓ Inconclusive	The title is vague and generic, using non-descriptive phrasing that doesn't convey the comprehensive redesign of the style guide.	Consider a more specific title like 'Redesign style guide with Oxygen UI architecture and migration guidance' to better reflect the major updates.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/STYLE-GUIDE.md`:
- Around line 58-63: Update the fenced code block in STYLE-GUIDE.md that shows
the component hierarchy so it includes a language specifier; change the
triple-backtick fence surrounding the lines starting with "Pages (routes)" and
the tree to use ```text (or leave unmarked for plain text) so the block renders
with the intended formatting.

🧹 Nitpick comments (1)

docs/STYLE-GUIDE.md (1)

432-448: Consider improving type safety for dark mode access.

The example uses (theme as any) to access colorSchemes.dark, which bypasses TypeScript's type safety. This suggests the theme types may not properly expose the colorSchemes property.

💡 Potential improvement

Consider creating a typed helper or extending the Theme interface to avoid the any cast:

// In a types file
import { Theme as MuiTheme } from "@oxygen-ui/react/models/theme";

interface ExtendedTheme extends MuiTheme {
    colorSchemes?: {
        dark: {
            palette: {
                background: { default: string };
                text: { primary: string };
            };
        };
    };
}

// Usage
const theme = useTheme() as ExtendedTheme;
const darkBg = theme.colorSchemes?.dark.palette.background.default;

If the library doesn't expose these types, document this as a known limitation in the style guide.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add language specifier to fenced code block.

The fenced code block lacks a language specifier. Add text or leave it unmarked for plain text display.

📝 Proposed fix

-```
+```text
 Pages (routes)
     └── Features (business logic containers)
         └── Compositions (component combinations)
             └── Base Components (atoms/molecules)

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

58-58: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

In `@docs/STYLE-GUIDE.md` around lines 58 - 63, Update the fenced code block in
STYLE-GUIDE.md that shows the component hierarchy so it includes a language
specifier; change the triple-backtick fence surrounding the lines starting with
"Pages (routes)" and the tree to use ```text (or leave unmarked for plain text)
so the block renders with the intended formatting.

[pavinduLakshan]

Suggested change

	**Oxygen UI** (`@oxygen-ui/react`) is our design system built on MUI. It provides consistent theming, accessibility, and alignment with WSO2's product design language.
	**Oxygen UI** (`@oxygen-ui/react`) is our design system built on MUI. It provides consistent theming, accessibility, and alignment with WSO2's product design guidelines.