[Doc] Add feature docs related to themes, layouts, and i18n support#3017
[Doc] Add feature docs related to themes, layouts, and i18n support#3017NutharaNR wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation guides for two feature areas: Design system customization (themes and layouts) and internationalization/localization (translation management). Four new MDX documentation pages and two sidebar category configurations are introduced, with sidebar navigation updated to surface these guides. ChangesDesign and Localization Guide Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
NutharaNR
force-pushed
the
doc-update-themes-layouts-i18n
branch
9 times, most recently
from
82fd82e to
5ebbb9e
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/guides/guides/design/layouts.mdx`:
- Line 390: Replace the flagged sentence "Unassign the layout from all
applications before deleting it." with a rephrasing that avoids the word
"Unassign" but keeps the meaning—e.g., "Remove the layout from all applications
before deleting it." Update that line in the layouts.mdx content so it still
reads: "You cannot delete a layout that is currently assigned to an application.
Remove the layout from all applications before deleting it."
- Line 408: The link href "../../i18n/localization-support" in
docs/content/guides/guides/design/layouts.mdx is stale and should point to the
new doc introduced here; update the href to "../../i18n/localization" (or the
correct new slug if different) wherever the old link appears so the Next Steps
link resolves to the renamed localization page.
In `@docs/content/guides/guides/design/overview.mdx`:
- Line 23: Update the stale link targets in overview.mdx: replace occurrences of
"/docs/next/guides/guides/i18n/localization-support" with the new
"/docs/next/guides/guides/i18n/localization" (appears in the line with "To
localize screen text" and the other occurrence around line 52) so both links
point to the renamed localization doc.
In `@docs/content/guides/guides/design/themes.mdx`:
- Line 343: Replace the outdated Next Steps link href value
"../../i18n/localization-support" with the new localization page path
"../../i18n/localization" in the docs content (look for the
href="../../i18n/localization-support" occurrence in themes.mdx) so the Next
Steps link points to the renamed localization page.
- Line 44: Change the problematic wording so Vale no longer flags "dialogs" and
"Unassign": replace "cards and dialogs" with "cards and dialog boxes" (or "cards
and dialog components") in the line that currently reads "Blur effects create
frosted glass (acrylic) backgrounds on cards and dialogs.", and update any
instances of "Unassign" in the document to sentence-case "unassign" or rephrase
the text to avoid the flagged token; apply the same fixes at the other two
occurrences reported (the lines mentioned around 81 and 329).
In `@docs/content/guides/guides/i18n/localization.mdx`:
- Line 21: Replace the hardcoded brand phrase "Thunder-specific" in the sentence
describing SDK translation bundles with the MDX product template; specifically,
swap the literal "Thunder-specific" for a templated form using the ProductName
component (e.g., use "<ProductName />-specific" or "SDKs for <ProductName />")
so the prose uses the MDX product templating mechanism instead of the raw
literal and preserves the rest of the sentence about locales and the en-US
fallback.
In `@docs/content/guides/guides/i18n/manage-translations.mdx`:
- Line 330: Update the stale markdown link target in manage-translations.mdx:
replace the reference target "../localization-support" used in the
"[Localization Support]" link with the new localization doc path (e.g.,
"../localization" or the correct relative path to the added localization
document) so the "[Localization Support]" link resolves to the new localization
page.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c918e2ce-4908-4d57-a43d-b6d948d92000
📒 Files selected for processing (8)
docs/content/guides/guides/design/_category_.jsondocs/content/guides/guides/design/layouts.mdxdocs/content/guides/guides/design/overview.mdxdocs/content/guides/guides/design/themes.mdxdocs/content/guides/guides/i18n/_category_.jsondocs/content/guides/guides/i18n/localization.mdxdocs/content/guides/guides/i18n/manage-translations.mdxdocs/sidebars.ts
NutharaNR
force-pushed
the
doc-update-themes-layouts-i18n
branch
from
5ebbb9e to
5f531a7
Compare
NutharaNR
force-pushed
the
doc-update-themes-layouts-i18n
branch
from
5f531a7 to
1d472fa
Compare
ThaminduDilshan
added
documentation
| Because these two areas are independent, you can update a theme without affecting the layout, and vice versa. | ||
|
|
||
| :::tip | ||
| To localize screen text, see [Translations](/docs/next/guides/guides/i18n/localization). |
There was a problem hiding this comment.
Clicking on Translations goes to Localization page. Is this intentional? Experience seems bit off right?
| ::: | ||
|
|
||
| :::note | ||
| When Declarative Mode is enabled, themes and layouts become read-only. You cannot update or delete them. |
There was a problem hiding this comment.
Themes and layouts will be read-only, only if these have been defined as declarative resources right?
By reading this, I got the initial impression all themes and layouts will be read only when declarative config is enabled
|
|
||
| ## How Design Is Applied | ||
|
|
||
| Design configurations are scoped per application or organizational unit. Each application or unit can have its own theme and layout. When a user opens an authentication screen, <ProductName /> resolves the matching design configuration for that context and renders the screen accordingly. |
There was a problem hiding this comment.
| Design configurations are scoped per application or organizational unit. Each application or unit can have its own theme and layout. When a user opens an authentication screen, <ProductName /> resolves the matching design configuration for that context and renders the screen accordingly. | |
| Design configurations are scoped per application or organizational unit. Each application or organization unit can have its own theme and layout. When a user opens an authentication screen, <ProductName /> resolves the matching design configuration for that context and renders the screen accordingly. |
| </Stepper> | ||
|
|
||
| </TabItem> | ||
| <TabItem value="api" label="API"> |
There was a problem hiding this comment.
Do we need these two tab version? Have we followed this in any other places?
IIRC our current approach is to write feature docs for the console try out experience. If they're using APIs, they have to refer API docs. But we have API walkthrough in some places where we don't have console implementation.
@himeshsiriwardana correct me if I'm wrong
|
|
||
| <Stepper stepNode="h3" as="h3"> | ||
|
|
||
| ### Step 1: Open the Theme Creator |
There was a problem hiding this comment.
I'd prefer to have "Theme Builder" here aligning with the "Flow Builder". But let's see other's opinions.
|
|
||
| Each theme includes the following configurable properties. | ||
|
|
||
| ### Color Schemes |
There was a problem hiding this comment.
Shall we keep only the basic details before the "Create a Theme" section and extract everything else to a catalog or similar doc?
Having explanations for all of these configurations before the walkthrough introduces a bit of overhead when reading feature docs.
Same applies to Layouts too
| </Tabs> | ||
|
|
||
| :::warning | ||
| You cannot delete a theme that is currently assigned to an application. Remove the theme from all applications before deleting it. |
There was a problem hiding this comment.
Not sure this validation is implemented as of now. Probably it's not there. Maybe can warn this is a permanent delete and cannot revert. Similar warning should be somewhere else in the docs already
|
|
||
| A layout defines the structural composition of authentication screens. While a [theme](../themes) controls visual styling (colors, fonts), a layout controls how screen elements are arranged. This includes the header, main content area, and footer slots, along with their sizing, spacing, and visibility. | ||
|
|
||
| ## Screen Types |
There was a problem hiding this comment.
Do we have support for different screens in the current implementation? I don't think so
| | `recovery` | Account recovery options screen. | | ||
| | `password-reset` | Password reset completion screen. | | ||
|
|
||
| ### Screen Inheritance |
There was a problem hiding this comment.
Let's validate this is valid. Not sure such a configurations exists in the current implementation
| import TabItem from '@theme/TabItem'; | ||
| import {NextSteps, NextStepsCard} from '../../../../src/components/NextSteps'; | ||
|
|
||
| # Layouts |
There was a problem hiding this comment.
Shall we recheck the layout docs with the implementation?
IIRC we only support centered layout as of now and is only possible to configure custom CSS, at least in the frontend
There was a problem hiding this comment.
API spec seems to be outdated. Shall we check and update the api swagger definition too?
cc: @DonOmalVindula
|
|
||
| Each language is identified by a BCP 47 language tag such as `en-US`, `fr-FR`, or `ja-JP`. When a user opens an authentication screen, <ProductName /> resolves the appropriate translations for that language and renders all text accordingly. | ||
|
|
||
| The <ProductName />-specific SDKs ship with built-in translation bundles for the following locales. English (`en-US`) serves as the fallback: |
There was a problem hiding this comment.
We don't provide these language bundles in the console or backend. These are pure SDK fallbacks. IMO it's better to remove these from docs and only have en-US.
@DonOmalVindula @brionmario any thoughts?
|
|
||
| <ProductName /> lets you add, update, and delete translations through the <ProductName /> Console or the i18n API. You can list available languages, resolve translations at runtime, and create or remove custom translation overrides. | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Better to build experience around console here. At least that's what we've been following as of now.
| | Key | Alphanumeric characters, dots, underscores, and hyphens. Maximum 256 characters. | `forms.credentials.title`, `forms.username.title` | | ||
| | Value | Non-empty string. Maximum 4096 characters. | `Welcome back` | | ||
|
|
||
| ## Error Codes |
There was a problem hiding this comment.
Better to have these in a catalog page. @himeshsiriwardana WDYT?
3 participants
Purpose
Adds documentation for two new feature areas in the Guides section: Design and Translations.
Design
Covers how to customize the visual appearance and structural layout of authentication screens (sign-in, sign-up, recovery, consent) to match a brand. The section is structured as:
Translations
Covers built-in i18n support for localizing authentication screen text into user-preferred languages using BCP 47 language tags. The section is structured as:
Also updates sidebars.ts to register both new sections.
Approach
Related Issues
Related PRs
Checklist
breaking changelabel added.Security checks
Summary by CodeRabbit