injast-core 1.0.80 → 1.0.82

package/guidelines/components/forms.md

@@ -4,10 +4,15 @@
 
 - Use controlled components for form values.
 - Use `TextField` instead of raw `<input>`.
-- Put labels on every input unless the context is visually obvious.
+- Use Injast Core inputs for every generated field. Choose `TextField`, `NumberInput`, `InputPhoneNumber`, `CardNumberInput`, `OtpInput`, `Select`, `MultiSelect`, `Autocomplete`, `Checkbox`, `Radio`, `Toggle`, `Slider`, or `CounterBoxInput` before direct Material UI or raw HTML controls.
+- Do not import direct Material UI input primitives in generated app code when an Injast input exists.
+- Put labels on every input unless the surrounding context makes the value unmistakable.
 - Use `error` and `helperText` for validation messages.
 - Use 48px control height for default forms.
 - Use RTL layout for Persian forms.
+- Use `gap: 3` to `gap: 4` between related fields.
+- Use `gap: 1` to `gap: 2` between field labels/helper copy and the field.
+- Do not place required fields inside collapsed accordions.
 
 ## TextField
 
@@ -20,17 +25,62 @@
 | `height` | `number` | Explicit field height |
 
 ```tsx
+import { SearchNormal1 } from "iconsax-react";
+import { TextField, defaultColors } from "injast-core";
+
 <TextField
   label="نام"
   value={name}
   onChange={(event) => setName(event.target.value)}
   height={48}
+  startAdornment={<SearchNormal1 size={20} color={defaultColors.neutral.main} />}
+/>
+```
+
+Sizing:
+
+- Default height: 48px.
+- Radius: 8px.
+- Input adornment icon: 20px.
+- Use `fullWidth` in mobile forms and 520px app shells.
+- Use `dir="ltr"` only for Latin codes, OTP, card numbers, phone-like numeric values, or technical identifiers.
+
+## Form Wrappers
+
+Use `FormControl`, `InputLabel`, `MenuItem`, and `FormControlLabel` when composing Material UI-compatible form groups.
+
+Rules:
+
+- Use `FormControl` to bind labels, helper text, and selection controls into one accessible group.
+- Use `InputLabel` with `Select`, `MultiSelect`, or custom field groups that need a floating label.
+- Use `MenuItem` only inside `Select` or menu-like option lists.
+- Use `FormControlLabel` for `Checkbox`, `Radio`, and `Toggle` labels.
+- In RTL forms, use `labelPlacement="start"` when the visual layout needs the control on the trailing side, as in drawer radio lists.
+
+## Autocomplete
+
+Use `Autocomplete` when users choose from a longer list, need search-as-you-type, or may need multiple searchable selections.
+
+```tsx
+<Autocomplete
+  options={options}
+  getOptionLabel={(option) => option.label}
+  renderInput={(params) => (
+    <TextField {...params} label="دسته بندی" height={48} fullWidth />
+  )}
 />
 ```
 
+Rules:
+
+- Render the input with Injast `TextField`.
+- Keep the field 48px tall unless the surrounding UI is intentionally dense.
+- Use `multiple` only when selected values are naturally a set.
+- Prefer `Select` for short static lists and `Autocomplete` for longer or searchable lists.
+
 ## Select and MultiSelect
 
-Use `Select` for a single value and `MultiSelect` for multiple values.
+Use `Select` for one value and `MultiSelect` for multiple values.
 
 ```tsx
 <MultiSelect
@@ -44,15 +94,74 @@ Use `Select` for a single value and `MultiSelect` for multiple values.
 />
 ```
 
+Rules:
+
+- Use 48px height and 8px radius.
+- `MultiSelect` default `minWidth` is `13rem`; override only when the layout needs a tighter or full-width control.
+- MultiSelect chips use a neutral surface, pill radius, `px: 3`, `py: 1.5`, and compact 18px remove icons.
+- Keep option labels short enough to scan in Persian.
+
 ## Boolean Inputs
 
-- Use `Checkbox` for independent form choices.
-- Use `RadioGroup` when the user must choose one option from a short list.
-- Use `Toggle` for settings that take effect as on/off state.
+Use `Checkbox` for independent form choices. The default checkbox icon is 24px with 4px corner radius.
+
+Checkbox customization props:
+
+| Prop | Use for |
+|---|---|
+| `iconSize` | Custom checkbox square size; default is 24px |
+| `borderColor` | Unchecked border color override |
+| `checkedBorderColor` | Checked border color fallback when theme primary is not available |
+| `backgroundColor` | Checked square background override |
+| `tickColor` | Checkmark color fallback when theme primary is not available |
+
+Prefer theme primary and neutral colors before custom checkbox colors.
+
+Use `RadioGroup` when the user must choose one option from a short list. Keep radio labels short and avoid more than 5 options before considering a select.
+
+Use `Toggle` for settings that take effect as an on/off state.
+
+Toggle sizing:
+
+| Size | Track |
+|---|---:|
+| `small` | 48px by 26px |
+| `medium` | 59px by 32px |
+
+Toggle props:
+
+- Use `checked` for controlled on/off state.
+- Use `onChange` to update the controlled value.
+- Use `disabled` when the setting cannot currently change.
+- Use custom `color` only when the theme primary color is not appropriate.
+
+## Slider
+
+Use `Slider` for bounded numeric ranges where dragging is faster than typing.
+
+Rules:
+
+- Always provide `min`, `max`, and `step` when the domain is known.
+- Show the current value in nearby text when precision matters.
+- Use `NumberInput` instead when users need exact manual numeric entry.
+- Keep horizontal sliders at least 240px wide on mobile.
+
+## Phone Input
+
+Use `InputPhoneNumber` for Iranian phone numbers instead of a normal `TextField`.
+
+Rules:
+
+- It normalizes Persian and Arabic numerals to ASCII digits.
+- It accepts `+98`, `0098`, `98`, and 10-digit mobile numbers that start with `9`, then normalizes to a leading `0`.
+- Default `maxDigitLength` is 11.
+- Use `dir="rtl"` by default; use `dir="ltr"` only when the surrounding form needs Latin number alignment.
+- Pass `inputRef` when parent logic needs focus control.
+- Use `onBlur` for touched/validation behavior.
 
 ## Numeric Inputs
 
-Use `NumberInput` for formatted numeric entry. Use `fungible` when decimals are allowed.
+Use `NumberInput` for formatted numeric entry.
 
 ```tsx
 <NumberInput
@@ -63,6 +172,62 @@ Use `NumberInput` for formatted numeric entry. Use `fungible` when decimals are
 />
 ```
 
-Use `CardNumberInput` for bank card numbers; it returns the cleaned digits to `onChange`.
+Rules:
+
+- Use `fungible` when decimals are allowed.
+- `NumberInput` returns the cleaned numeric string to `onChange`.
+- Use `unit` for currency or measurement labels.
+- Use `hasClearButton` only when reset is a useful action.
+- Pair `hasClearButton` with `onReset`.
+- Use `maxLength` and `minLength` when the numeric identifier has length rules.
+- Do not use `type="number"` raw inputs for Persian numeric forms.
+
+## Card and OTP Inputs
+
+Use `CardNumberInput` for Iranian bank card numbers. It displays groups with dashes and returns cleaned digits to `onChange`.
+
+Rules:
+
+- Use `bankLogo` for a 20px bank logo at the start of the field when detected.
+- Use `hasClearButton` only when users often need to reset the field.
+- Pair `hasClearButton` with `onReset`.
+- Keep the visible field RTL context-friendly, but the card number itself behaves as numeric input.
 
 Use `OtpInput` for verification codes, not a normal text field.
+
+OTP sizing:
+
+- Default cell: 54px by 54px.
+- Cell radius: 8px.
+- Cell padding: 8px vertical.
+- Direction: LTR.
+- Text alignment: center.
+- Use 4 or 6 cells depending on the verification flow.
+- Use `focusedBorderColor` to customize the focused cell border.
+- Use `backgroundColor` for a custom cell background only when the product surface requires it.
+- Use the `error` prop to show danger-colored cell borders.
+
+Use `IosHiddenOtpInput` only as an invisible iOS one-time-code autofill bridge beside a visible `OtpInput`. It renders a 1px hidden input, focuses on iOS, normalizes Persian/Arabic digits to Latin digits, and calls `onOtpChange`.
+
+Rules:
+
+- Do not use `IosHiddenOtpInput` as the visible OTP UI.
+- Keep the visible code cells in `OtpInput`.
+- Use it only on client-side screens where `navigator.userAgent` and `document` are available.
+
+## CounterBoxInput
+
+Use `CounterBoxInput` for stepper-like numeric changes where increment and decrement actions are central to the workflow.
+
+Rules:
+
+- Default field height is 48px.
+- Plus/minus controls are 32px square.
+- Keep the unit visible when the number depends on currency, inventory, or quantity.
+- Set `min`, `max`, and `step` explicitly when business rules exist.
+- Use `allowFloat` for decimal steps.
+- `defaultValue` is kept for API compatibility; prefer controlled `value`.
+- Use `disabledInput` when the field should only change through plus/minus controls.
+- Use `iconColor` and `iconBackgroundColor` sparingly; prefer neutral defaults.
+- Use `minErrText`, `maxErrText`, and `maxAvailable` for domain-specific bounds.
+- Use `mb` only to reserve vertical space when helper/error text is shown.

package/guidelines/components/layout.md

@@ -1,8 +1,48 @@
 # 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: 520,
+    mx: "auto",
+    minHeight: "100dvh",
+    bgcolor: "neutral.50",
+  }}
+>
+  {children}
+</Box>
+```
+
+Equivalent CSS:
+
+```css
+max-width: 520px;
+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.
+- Do not implement mobile OS status bars or decorative app status bars, even when present in Figma frames.
+- Wire screens into flows. Back, home, receipt/history, submit, confirm, close, and selection actions should navigate or update local state instead of acting as static placeholders.
+
+## Layout Primitives
 
 ```tsx
 <Container maxWidth="lg">
@@ -14,23 +54,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 520px 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 520px 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 520px 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} />}
+/>
+```