injast-core 1.0.80 → 1.0.81

package/guidelines/components/layout.md

@@ -1,8 +1,46 @@
 # Layout and Navigation
 
-## Layout Primitives
+## App Shell
 
-Use `Box`, `Container`, and `Grid` for page structure.
+Most generated Injast screens should be mobile-first and centered:
+
+```tsx
+import { Box } from "injast-core";
+
+<Box
+  sx={{
+    maxWidth: 550,
+    mx: "auto",
+    minHeight: "100dvh",
+    bgcolor: "neutral.50",
+  }}
+>
+  {children}
+</Box>
+```
+
+Equivalent CSS:
+
+```css
+max-width: 550px;
+margin-inline: auto;
+```
+
+Use this shell for authentication, onboarding, profile, checkout, settings, forms, and mobile operational flows.
+
+Use a wider layout only for desktop-first dashboards, large tables, chart-heavy analytics, or split-pane workflows. Even then, keep forms and drawers constrained to readable widths.
+
+## Page Composition
+
+- Use `Box`, `Container`, and `Grid` for structure.
+- Use page padding inside the shell: `px: 4`, `py: 4` to `py: 6`.
+- Use `display="grid"` or `display="flex"` with `gap`, not stacked arbitrary margins.
+- Use `gap: 4` to `gap: 6` between major sections.
+- Use `gap: 3` to `gap: 4` inside field groups and card content.
+- Keep a hint of the next section visible on the first viewport when building long mobile flows.
+- Do not create landing-page heroes for app/tool requests.
+
+## Layout Primitives
 
 ```tsx
 <Container maxWidth="lg">
@@ -14,23 +52,85 @@ Use `Box`, `Container`, and `Grid` for page structure.
 
 Rules:
 
-- Use `gap`, `p`, `px`, `py`, `m`, and `mx` from MUI spacing.
-- Use `Container` to constrain broad pages.
+- Use `Container` to constrain broad desktop pages.
+- Use `Box` for app shells, stacks, rows, and framed repeated items.
 - Use `Grid` for responsive multi-column layouts.
+- Use MUI spacing props: `gap`, `p`, `px`, `py`, `m`, `mx`, `my`.
 - Avoid raw CSS layout unless component props are not enough.
 
+## Fixed Bottom Actions
+
+For mobile forms with a clear final action, use a bottom action band:
+
+- Shell width remains 550px max and centered.
+- Use `position: "sticky"` or `position: "fixed"` only when the action must stay visible.
+- Use `px: 4`, `py: 3`, neutral/white background, and a subtle top border.
+- Use a full-width `Button buttonSize="M"` for the primary action.
+- Ensure the scroll content has bottom padding so fields are not hidden behind the action band.
+
+## Sticky App Regions
+
+For chat, assistant, or app-like flows, use a sticky header and sticky bottom input/action area inside the 550px shell.
+
+Header rules:
+
+- Height: 56px.
+- Background: `neutral.100` or the page canvas color.
+- Padding: `p: 4` (16px) unless the header is extremely dense.
+- Use Iconsax 20px icons for back, home, menu, and disclosure controls.
+- Use 32px to 40px icon button targets with 12px radius for compact header controls.
+- Truncate long titles with `overflow: "hidden"`, `textOverflow: "ellipsis"`, and `whiteSpace: "nowrap"`.
+
+Bottom input/action rules:
+
+- Use `position: "sticky"` or a sticky `.input-area` at `bottom: 0`.
+- Use `p: "10px 16px"`, `gap: "8px"`, and `bgcolor: "neutral.100"`.
+- Keep the message/input field container at 12px radius.
+- Use a 48px square submit/send `Button` when the input sits beside the action.
+- Keep the scrollable content area as `flex: 1` with `overflowY: "auto"`.
+
+Chat bubble rules:
+
+- Use `gap: "8px"` and `mb: "8px"` between message rows.
+- Message bubble max width should leave avatar/action space, for example `maxWidth: "calc(100% - 70px)"`.
+- Bubble padding can use `p: "8px 18px"`.
+- Bubble radius should be 12px, with one corner squared to show sender direction when useful.
+- User messages can use `primary.main` with `primary.contrastText`; bot/system messages should use white or neutral surfaces with `neutral.700` text.
+
 ## Lists
 
 Use `List` and `ListItem` for vertical collections. Keep each row's main label, metadata, and action placement consistent.
 
+Rules:
+
+- Keep row actions on the trailing side in RTL.
+- Use icons only when they speed recognition.
+- Use stable row heights for repeated lists.
+
 ## Accordion
 
-Use `Accordion`, `AccordionSummary`, and `AccordionDetails` for optional details, filters, and FAQ-like disclosure. Do not hide primary required fields in an accordion.
+Use `Accordion`, `AccordionSummary`, and `AccordionDetails` for optional details, filters, and FAQ-like disclosure.
+
+Do not hide required primary fields or blocking errors inside an accordion.
 
 ## Tabs
 
 Use `Tab` when switching between closely related panels at the same hierarchy level. Do not use tabs as primary app navigation.
 
+Tab rules:
+
+- Pass `tabs` as `{ label, value }[]`.
+- Use `activeTab` for a controlled initial/active value.
+- `onChange` receives the selected tab value.
+- Default `fontSize` is 14px; reduce only for dense segmented controls.
+- Tab height is 48px with 12px radius and an active underline.
+
 ## Stepper
 
-Use `Stepper` and related step components for multi-step flows such as onboarding, checkout, or profile completion. Keep the active step clear and provide Back/Next actions with `Button`.
+Use `Stepper` and related step components for multi-step flows such as onboarding, checkout, or profile completion.
+
+Rules:
+
+- Keep the active step clear.
+- Provide Back/Next actions with `Button`.
+- Keep step content width readable; 400px to 550px works well for form flows.

package/guidelines/components/overview.md

@@ -2,28 +2,46 @@
 
 Always prefer Injast Core components over raw HTML and direct Material UI primitives. Read the focused guideline file before using a component group.
 
+## Selection Rules
+
+- Use root imports from `injast-core` for normal Make output.
+- Use `iconsax-react` for all generated app icons.
+- Use `Box`, `Container`, and `Grid` for layout instead of raw layout elements when possible.
+- Use `Typography` for visible text that participates in hierarchy.
+- Use `Button`, `IconButton`, and `Fab` for actions.
+- Use Injast form components for all inputs.
+- Use `Toast`, `Modal`, `Dialog`, `Loading`, and `Skeleton` for feedback.
+- Use `DataGrid` for tables and operational records.
+- Do not guess custom props. If a component is an MUI wrapper, use the matching Material UI props plus documented Injast-specific props.
+
 ## Actions
 
 | Component | Also known as | Purpose | Guidelines |
 |---|---|---|---|
 | `Button` | CTA, action button | Text actions, submit, navigation, commands | `buttons.md` |
-| `IconButton` | icon action | Compact icon-only actions | `buttons.md` |
+| `IconButton` | icon action | Compact icon-only actions | `buttons.md`, `../foundations/icons.md` |
 | `Fab` | floating action | Prominent floating action | `buttons.md` |
+| `SvgIcon` | masked SVG asset | Legacy/custom SVG mask rendering | `../foundations/icons.md` |
 
 ## Forms
 
 | Component | Also known as | Purpose | Guidelines |
 |---|---|---|---|
 | `TextField` | text input | General text entry | `forms.md` |
+| `Autocomplete` | searchable select, combobox | Search and select from longer option sets | `forms.md` |
 | `NumberInput` | numeric input | Controlled formatted number entry | `forms.md` |
 | `CardNumberInput` | bank card input | Iranian bank card number entry | `forms.md` |
 | `OtpInput` | verification code | One-time password entry | `forms.md` |
+| `IosHiddenOtpInput` | hidden iOS OTP helper | iOS one-time-code autofill bridge | `forms.md` |
 | `InputPhoneNumber` | phone input | Iranian phone number entry | `forms.md` |
+| `FormControl`, `InputLabel`, `MenuItem`, `FormControlLabel` | form wrappers | MUI-compatible form composition helpers | `forms.md` |
 | `Select` | dropdown | Single selection | `forms.md` |
 | `MultiSelect` | tag select | Multiple selection with removable chips | `forms.md` |
 | `Checkbox` | boolean check | Independent yes/no selection | `forms.md` |
 | `Radio`, `RadioGroup` | radio buttons | One choice from a short list | `forms.md` |
 | `Toggle` | switch | On/off setting | `forms.md` |
+| `Slider` | range input | Numeric range or stepped value selection | `forms.md` |
+| `CounterBoxInput` | stepper number input | Quantity or amount with plus/minus controls | `forms.md` |
 
 ## Feedback
 
@@ -31,13 +49,14 @@ Always prefer Injast Core components over raw HTML and direct Material UI primit
 |---|---|---|---|
 | `Toast` | snackbar, alert | Brief status feedback | `feedback.md` |
 | `Modal`, `Dialog` | dialog, overlay | Focused task or confirmation | `feedback.md` |
+| `Drawer` | bottom sheet, side drawer | Mobile picker, filters, navigation drawer | `feedback.md`, `layout.md` |
 | `Loading`, `LoadingModal`, `CircularProgress`, `Skeleton`, `ProgressBar` | progress | Loading and progress states | `feedback.md` |
 
 ## Layout and Navigation
 
 | Component | Also known as | Purpose | Guidelines |
 |---|---|---|---|
-| `Box`, `Container`, `Grid` | layout primitives | Spacing and page structure | `layout.md` |
+| `Box`, `Container`, `Grid` | layout primitives | Spacing, shell, and page structure | `layout.md` |
 | `List`, `ListItem` | list | Vertical repeated items | `layout.md` |
 | `Accordion`, `AccordionSummary`, `AccordionDetails` | disclosure | Collapsible sections | `layout.md` |
 | `Tab` | tabs | Switch between related panels | `layout.md` |
@@ -48,8 +67,8 @@ Always prefer Injast Core components over raw HTML and direct Material UI primit
 | Component | Also known as | Purpose | Guidelines |
 |---|---|---|---|
 | `DataGrid` | table, grid | Tabular operational data | `data-display.md` |
-| `Typography` | text | Text hierarchy | `data-display.md` |
-| `Image` | image | Image rendering with fallback behavior | `data-display.md` |
+| `Typography` | text | Text hierarchy | `data-display.md`, `../foundations/typography.md` |
+| `Image` | image | Image rendering with object-fit behavior | `data-display.md` |
 | `Divider`, `Pagination` | separator, pager | Data and content structure | `data-display.md` |
 
 ## Date Inputs

package/guidelines/foundations/color.md

@@ -1,37 +1,22 @@
 # Color
 
-## Palette
+## Palette Source
 
-Use `defaultColors` from `injast-core/constants` or `injast-core` for semantic colors:
+Use `defaultColors` from `injast-core` or `injast-core/constants` for semantic color decisions:
 
 ```tsx
 import { defaultColors } from "injast-core";
 ```
 
-Core palette groups:
+The active Material UI theme combines `appColors` with `defaultColors`. Prefer theme palette references in `sx`:
 
-| Group | Use for |
-|---|---|
-| `neutral` | Text, borders, surfaces, low-emphasis UI |
-| `success` | Positive status and success feedback |
-| `danger` | Error and destructive status |
-| `warning` | Caution and warning status |
-| `info` | Informational status |
-| `teal` | Preferred Injast brand accent |
-| `blue`, `cyan`, `indigo`, `pink`, `orange`, `magenta`, `yellow`, `red` | Secondary accents and charts |
-
-## Rules
-
-- Use `primary` for the main action or active state.
-- Use `secondary` for supporting actions and neutral controls.
-- Use `neutral.50` to `neutral.200` for quiet surfaces and separators.
-- Use `danger`, `warning`, `info`, and `success` only for their matching status.
-- Avoid large saturated backgrounds. Keep strong colors for small highlights, badges, icons, and buttons.
-- Prefer theme palette references in `sx` when possible, for example `color: "neutral.700"`.
+```tsx
+<Box sx={{ bgcolor: "neutral.50", color: "neutral.900" }} />
+```
 
-## App Colors
+## Required App Colors
 
-Every provider requires `appColors.primary` and `appColors.secondary`:
+Every `ThemeProvider` and `SPAThemeProvider` requires `appColors.primary` and `appColors.secondary`.
 
 ```tsx
 const appColors = {
@@ -49,3 +34,41 @@ const appColors = {
   },
 };
 ```
+
+Use `primary` for the main action, active states, selected dates, selected tabs, and focused highlights. Use `secondary` for supporting neutral actions only when the UI needs a formal secondary brand color.
+
+## Core Palette Groups
+
+| Group | Key values | Use for |
+|---|---|---|
+| `neutral` | `50` to `900`, `main`, `light`, `dark` | Text, surfaces, borders, disabled UI, low-emphasis controls |
+| `success` | `light`, `main`, `dark` | Successful completion, positive status, confirmation feedback |
+| `danger` | `light`, `main`, `dark` | Errors, destructive actions, failed validation |
+| `warning` | `light`, `main`, `dark` | Caution, pending risk, warning feedback |
+| `info` | `light`, `main`, `dark` | Neutral information and helper status |
+| `teal` | `100` to `400`, `transparent` | Preferred Injast accent and brand-adjacent highlights |
+| `blue`, `cyan`, `indigo`, `pink`, `orange`, `magenta`, `yellow`, `red` | `100` to `400`, `transparent` | Charts, badges, secondary visual differentiation |
+
+## Surface Rules
+
+- Use `neutral.50` for the page canvas in mobile app shells.
+- Use white or `neutral.100` for contained sections and cards.
+- Use `neutral.200` and `neutral.300` for separators, field borders, and low-emphasis dividers.
+- Use `neutral.700` to `neutral.900` for primary text.
+- Use `neutral.500` to `neutral.600` for secondary labels, helper text, and icon-only inactive states.
+- Do not use `primary.main`, `danger.main`, `warning.main`, or other saturated colors as large page backgrounds.
+
+## Status Rules
+
+- Success feedback: `success.light` background, `success.main` icon/text/border.
+- Error feedback: `danger.light` background, `danger.main` icon/text/border.
+- Warning feedback: `warning.light` background, `warning.main` icon/text/border.
+- Info feedback: `info.light` background, `info.main` icon/text/border.
+- Destructive actions should be explicit and should not look like the normal primary action.
+
+## Hard Rules
+
+- Do not invent new semantic names such as `brand`, `accent`, or `surface` unless a local app defines them.
+- Do not hardcode colors when a `defaultColors` or theme palette value exists.
+- Do not create one-note pages dominated by teal, purple, blue, or orange. Keep most UI neutral and use color as signal.
+- Keep icons and text color paired with their status. Example: warning copy uses `warning.main`, not `primary.main`.

package/guidelines/foundations/icons.md

@@ -0,0 +1,72 @@
+# Icons
+
+## Icon Package
+
+Use `iconsax-react` for all generated app icons:
+
+```tsx
+import { Add, Calendar, CloseCircle, SearchNormal1, TickCircle } from "iconsax-react";
+```
+
+Do not use Lucide, Heroicons, Font Awesome, inline SVGs, emoji icons, or `@mui/icons-material` in generated screens.
+
+Brand marks, bot avatars, uploaded media, and product illustrations can use `Image` or project image assets. Functional UI icons such as close, send, search, calendar, menu, status, back, home, and add/remove should use `iconsax-react`.
+
+Use `SvgIcon` only for existing custom SVG mask assets that must be recolored and do not exist in Iconsax. Prefer Iconsax first for app controls.
+
+`SvgIcon` props:
+
+- `src`: path to the SVG mask asset.
+- `color`: mask color; default is black.
+- `size`: square width/height; default is 24px.
+
+## Sizes
+
+| Context | Size |
+|---|---:|
+| Input adornment | 20px |
+| Compact chip/remove icon | 18px |
+| Small inline action | 20px |
+| Standard button/action icon | 24px |
+| Toast/status icon | 28px |
+| Large FAB icon | 28px |
+
+## Color
+
+- Use `defaultColors.neutral.main` or `neutral.600` for inactive utility icons.
+- Use `defaultColors.neutral.dark` or `neutral.800` for high-emphasis icons.
+- Use `primary.main` for selected, focused, and primary action icons.
+- Use matching status colors for status icons: `success.main`, `danger.main`, `warning.main`, and `info.main`.
+- Disabled icons use `neutral.300` or `neutral.400`.
+
+## Variants
+
+- Use the default Iconsax variant for normal UI controls.
+- Use `variant="Bold"` for status icons in `Toast`-like feedback and high-certainty states.
+- Do not mix icon styles inside one toolbar or button group.
+
+## RTL Placement
+
+- Put leading icons in `startIcon` for actions that visually begin with an icon.
+- Put trailing icons in `endIcon` for navigation, disclosure, and calendar/date affordances.
+- Use logical spacing with `gap: 2`; do not use left/right margins unless an existing component requires it.
+- Icons that imply direction should match RTL flow. In RTL, forward movement normally points left and back movement points right.
+
+## Examples
+
+```tsx
+import { Calendar, SearchNormal1 } from "iconsax-react";
+import { TextField, defaultColors } from "injast-core";
+
+<TextField
+  label="جستجو"
+  height={48}
+  startAdornment={<SearchNormal1 size={20} color={defaultColors.neutral.main} />}
+/>
+
+<TextField
+  label="تاریخ"
+  height={48}
+  endAdornment={<Calendar size={20} color={defaultColors.neutral.dark} />}
+/>
+```

package/guidelines/foundations/spacing.md

@@ -2,33 +2,93 @@
 
 ## Base Spacing
 
-The theme sets Material UI spacing to 4px increments.
+The theme sets Material UI spacing to 4px increments. Use numeric `sx` values so spacing stays on this scale.
 
-| Value | Pixel equivalent |
-|---:|---:|
-| `1` | 4px |
-| `2` | 8px |
-| `3` | 12px |
-| `4` | 16px |
-| `6` | 24px |
-| `8` | 32px |
+| `sx` value | Pixel equivalent | Common use |
+|---:|---:|---|
+| `0.5` | 2px | Hairline label/icon nudge only |
+| `1` | 4px | Tiny icon or table-cell gap |
+| `1.5` | 6px | Compact chip vertical padding |
+| `2` | 8px | Tight internal gap, button/icon spacing |
+| `3` | 12px | Field group gap, chip horizontal padding |
+| `3.5` | 14px | Mobile side padding used by drawers/toasts |
+| `4` | 16px | Default section padding and content gap |
+| `5` | 20px | Dense page block spacing |
+| `6` | 24px | Major section gap and drawer vertical rhythm |
+| `8` | 32px | Large page break only |
 
-Use `sx` spacing props such as `p`, `px`, `py`, `m`, `gap`, `rowGap`, and `columnGap`.
+Use `p`, `px`, `py`, `m`, `mx`, `my`, `gap`, `rowGap`, and `columnGap` instead of arbitrary CSS margins.
+
+## App Shell
+
+Use this for generated mobile-first app screens:
+
+```tsx
+<Box
+  sx={{
+    maxWidth: 550,
+    mx: "auto",
+    minHeight: "100dvh",
+    bgcolor: "neutral.50",
+  }}
+>
+  {children}
+</Box>
+```
+
+Equivalent CSS:
+
+```css
+max-width: 550px;
+margin-inline: auto;
+```
+
+Rules:
+
+- Center the shell with `mx: "auto"` or `margin-inline: auto`.
+- Keep the shell full width below 550px.
+- Use `minHeight: "100dvh"` for app-like screens.
+- Apply page padding inside the shell, not on `body`.
+- Use wider layouts only for data-heavy desktop dashboards, large tables, or split-pane workflows.
+
+## Page Padding and Gaps
+
+| Context | Recommended spacing |
+|---|---|
+| Mobile page side padding | `px: 4` (16px) |
+| Dense page side padding | `px: 3.5` (14px) |
+| Page top/bottom padding | `py: 4` to `py: 6` (16px to 24px) |
+| Major sections | `gap: 4` to `gap: 6` (16px to 24px) |
+| Related form fields | `gap: 3` to `gap: 4` (12px to 16px) |
+| Label/helper text to field | `gap: 1` to `gap: 2` (4px to 8px) |
+| Inline icon to label | `gap: 2` (8px) |
+| Toolbar actions | `gap: 2` to `gap: 3` (8px to 12px) |
+| Modal content blocks | `gap: 4` (16px) |
+| Drawer content | `px: 3.5`, `py: 6` (14px, 24px) |
 
 ## Component Sizing
 
-- Default form controls and medium buttons are 48px tall.
-- Large buttons are 56px tall.
-- Small buttons and dense controls are 40px tall.
-- Extra small buttons are 32px tall.
-- Standard field radius is 8px.
-- Button radius is 8px or 12px depending on size.
-- Modal paper radius is 12px.
-
-## Layout Rules
-
-- Use `Box`, `Container`, and `Grid` for spacing and layout.
-- Use 16px to 24px gaps between major sections.
-- Use 8px to 12px gaps inside compact controls and field groups.
-- Keep repeated cards and table rows stable in height.
-- Avoid nested cards unless the inner card is a true repeated item or modal content.
+| Component or pattern | Size |
+|---|---:|
+| Default text fields | 48px height |
+| `Button` `L` | 56px height, 12px radius |
+| `Button` `M` | 48px height, 12px radius |
+| `Button` `S` | 40px height, 8px radius |
+| `Button` `XS` | 32px height, 8px radius |
+| Small IconButton target | 32px minimum |
+| Standard icon action target | 40px to 48px |
+| OTP input cell | 54px by 54px |
+| Checkbox icon | 24px by default |
+| Toggle small | 48px by 26px |
+| Toggle medium | 59px by 32px |
+| Progress bar default | 20px height |
+| Modal paper radius | 12px |
+| Text field radius | 8px |
+
+## Density Rules
+
+- Keep default forms at 48px control height.
+- Use 40px controls only in dense toolbars, tables, or secondary rows.
+- Use 32px controls only for compact inline actions or modal footer secondary actions.
+- Keep repeated rows stable in height; do not let hover states or labels shift layout.
+- Avoid nested cards. Use spacing, headings, and dividers before adding another framed surface.

package/guidelines/foundations/typography.md

@@ -2,32 +2,55 @@
 
 ## Fonts
 
-Load `injast-core/fonts.css` once. The theme uses:
+Load `injast-core/fonts.css` once. The package includes Persian-friendly fonts:
 
-- `IRANYekanX` for standard Persian UI text
-- `IRANYekanXFaNum` where Persian numerals are preferred
+- `IRANYekanX` for standard Persian UI text.
+- `IRANYekanXFaNum` where Persian numerals are preferred.
 
-## Scale
+`SPAThemeProvider` uses `IRANYekanXFaNum` by default. `ThemeProvider` uses `IRANYekanX` by default. Do not replace the font family in generated screens unless the user explicitly asks.
 
-Use the theme typography scale through components. Important roles:
+## Theme Scale
 
-| Role | Size | Weight | Use for |
+Use `Typography` from `injast-core` and theme typography variants.
+
+| Variant | Size | Weight | Use for |
 |---|---:|---:|---|
-| `display1` | 32px | 700 | Rare page-level display headings |
-| `display2` | 24px | 700 | Page headings |
-| `display3` | 20px | 700 | Section headings |
+| `display1` | 32px | 700 | Rare top-level display heading |
+| `display2` | 24px | 700 | Main page heading in roomy screens |
+| `display3` | 20px | 700 | Section title or modal title |
 | `h1` | 18px | 500 | Dense page title |
-| `h2` | 16px | 500 | Panel heading |
-| `h3` | 14px | 500 | Small heading |
+| `h2` | 16px | 500 | Panel, drawer, and modal heading |
+| `h3` | 14px | 500 | Small section heading |
+| `title1` | 16px | 500 | Card title or list group title |
+| `title2` | 14px | 500 | Compact card/list title |
+| `title3` | 12px | 500 | Small title or table metadata |
+| `title4` | 10px | 500 | Very compact label title |
+| `input1` | 16px | 500 | Large input text |
+| `input2` | 14px | 500 | Default input text |
+| `input3` | 12px | 500 | Compact input text |
+| `button1` | 16px | 700 | Large and medium button text |
+| `button2` | 14px | 700 | Small button text |
+| `button3` | 12px | 700 | Extra small button text |
 | `body1` | 14px | 500 | Default body text |
-| `body2` | 12px | 500 | Secondary text |
-| `label1` | 12px | 400 | Captions and field metadata |
+| `body2` | 12px | 500 | Secondary body text and metadata |
+| `label1` | 12px | 400 | Captions, helper text, field metadata |
 | `label2` | 10px | 400 | Compact labels only |
 
-## Rules
+## Usage Rules
 
-- Use `Typography` from `injast-core` for text hierarchy.
-- Do not use oversized hero text inside app screens.
-- Use concise labels in buttons and form controls.
-- Keep numeric content readable; use Persian number formatting utilities when appropriate.
+- Use `display1`, `display2`, and `display3` sparingly. App screens should not look like landing pages.
+- Use `h1` or `display3` for most mobile page titles.
+- Use `h2` for drawer and modal titles.
+- Use `body1` for readable content and form helper paragraphs.
+- Use `body2`, `label1`, and `label2` only for secondary metadata.
+- Use concise Persian labels for buttons and fields. Avoid long button text that wraps.
+- Keep numeric content readable and use Persian number utilities when values are shown to users.
 - Do not set negative letter spacing.
+- Do not scale font size with viewport width.
+- Do not place hero-scale text inside cards, tables, drawers, or modals.
+
+## Alignment
+
+- Persian and RTL text should be right-aligned by default.
+- Numeric codes, OTP digits, card numbers, and Latin-only values can use `dir="ltr"` and centered or left alignment when needed.
+- Keep table headers and body cells right-aligned unless the column is numeric, currency, or an action column.