@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/.ai/guides/styling-props-spacing.md

@@ -0,0 +1,279 @@
+# Spacing
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Spacing in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-spacing--docs)
+
+These are all styling props related to changing the spacing of a component.
+
+## Padding
+
+There are seven props you can use to customise the padding of any component. It accepts the entire spacing token spectrum.
+
+- `p`: Change the padding on all axes
+- `px`: Change the padding on the left and right of a component
+- `py`: Change the padding on the top and bottom of a component
+- `pl`: Change the padding on the left of a component
+- `pr`: Change the padding on the right of a component
+- `pt`: Change the padding on the top of a component
+- `pb`: Change the padding on the bottom of a component
+
+```tsx
+<IressSpacing bg="alt" p="xl">
+  A panel that has extra large padding on all sides.
+</IressSpacing>
+```
+
+[View "padding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--padding)
+
+```tsx
+<IressButton px={px} mode="primary">
+Submit
+</IressButton>
+```
+
+[View "button" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--button)
+
+```tsx
+<IressSpacing bg="alt" pb="xl" pt="spacing.1" pl="md" pr="spacing.6">
+  A panel that has different padding on each side.
+</IressSpacing>
+```
+
+[View "variablePadding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--variable-padding)
+
+### Responsive padding
+
+All padding props are responsive and can be changed according to different screen sizes.
+
+```tsx
+<IressSpacing bg="alt">
+  A panel that has extra large padding on small screens and no padding on large screens.
+</IressSpacing>
+```
+
+[View "responsivePadding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--responsive-padding)
+
+```tsx
+<IressSpacing bg="alt">
+  A panel that has responsive padding on the vertical and horizontal axes.
+</IressSpacing>
+```
+
+[View "responsiveVariablePadding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--responsive-variable-padding)
+
+### Migrating from version 5
+
+Responsive padding worked differently in version 5. The `p` prop no longer accepts a nested object of axes to change the padding, you must change every prop based on the breakpoint.
+
+```tsx
+<DiffViewer
+oldValue={`<IressPanel p={{ t: 'xl', b: 'xl' }} />`}
+newValue={`<IressPanel pt="xl" pb="xl" />`}
+/>
+```
+
+[View "MigratingPadding" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--migrating-padding)
+
+## Margin
+
+There are seven props you can use to customise the margin of any component. It accepts the entire spacing token spectrum, `auto` and negative values of the spacing token spectrum.
+
+- `m`: Change the margin on all axes
+- `mx`: Change the margin on the left and right of a component
+- `my`: Change the margin on the top and bottom of a component
+- `ml`: Change the margin on the left of a component
+- `mr`: Change the margin on the right of a component
+- `mt`: Change the margin on the top of a component
+- `mb`: Change the margin on the bottom of a component
+
+```tsx
+<IressSpacing bg="alt" m="xl">
+  A panel that has the same margin on all sides.
+</IressSpacing>
+```
+
+[View "margin" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--margin)
+
+```tsx
+<IressSpacing bg="alt" mb="xl" mt="spacing.1" ml="md" mr="spacing.6">
+  A panel that has different margin on each side.
+</IressSpacing>
+```
+
+[View "variableMargin" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--variable-margin)
+
+### Responsive margin
+
+All margin props are responsive and can be changed according to different screen sizes.
+
+```tsx
+<IressSpacing bg="alt">
+  A panel that has extra large margin on small screens and no margin on large screens.
+</IressSpacing>
+```
+
+[View "responsiveMargin" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--responsive-margin)
+
+```tsx
+<IressSpacing bg="alt">
+  A panel that has responsive margin on the vertical and horizontal axes.
+</IressSpacing>
+```
+
+[View "responsiveVariableMargin" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--responsive-variable-margin)
+
+### Negative margin
+
+Negative margin is supported in the same way as positive margin. You can use the same props to set negative margin.
+
+```tsx
+<IressPanel bg="colour.primary.surface" maxWidth="container.sm" mx="auto">
+<IressPanel />
+</IressPanel>
+```
+
+[View "negativeMargin" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--negative-margin)
+
+## `noGutter`
+
+The `noGutter` prop removes the bottom margin of the last direct child of a component. This is useful when you have nested content inside a component with padding, such as `IressPanel` or `IressCard`, to remove unnecessary spacing in your layout.
+
+```tsx
+<IressPanel>
+{children ?? (
+<ul>
+<li>
+{args.noGutter ? (
+<>
+Margin is removed due to <code>noGutter</code>
+</>
+) : (
+'Since lists have bottom margin, you can see there is extra white-space.'
+)}
+</li>
+</ul>
+)}
+</IressPanel>
+```
+
+[View "noGutter" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-spacing--no-gutter)
+
+---
+
+## Best Practices
+
+Always use spacing tokens from the design system scale instead of hardcoded pixel values. This ensures visual consistency and rhythm across your application.
+
+### ✅ DO: Use spacing token aliases
+
+The spacing scale provides convenient aliases (`xs`, `sm`, `md`, `lg`, `xl`) that map to specific pixel values.
+
+```tsx
+// ✅ CORRECT - Using aliases
+<IressPanel p="xl">Extra large padding (48px)</IressPanel>
+<IressStack spacing="md">Medium gap between items (16px)</IressStack>
+```
+
+### ✅ DO: Use full token names
+
+You can also use the full token names (e.g., `spacing.4`) for the same effect as aliases.
+
+```tsx
+// ✅ CORRECT - Using full token names
+<IressPanel p="spacing.10">Same as xl (48px)</IressPanel>
+<IressStack spacing="spacing.4">Same as md (16px)</IressStack>
+```
+
+### ✅ DO: Use directional props for precise control
+
+Use directional spacing props (`px`, `py`, `pl`, `pr`, `pt`, `pb`) when you need different spacing on different axes.
+
+```tsx
+// ✅ CORRECT - Directional spacing with tokens
+<IressPanel px="lg" py="sm">
+  Horizontal padding: large (24px), Vertical padding: small (8px)
+</IressPanel>
+```
+
+### ❌ DON'T: Use hardcoded pixel values
+
+Hardcoded pixel values break the design system's visual rhythm and don't adapt to spacing scale changes.
+
+```tsx
+// ❌ INCORRECT - Hardcoded pixel values
+<IressPanel style={{ padding: '24px' }}>Content</IressPanel>
+
+// ✅ CORRECT - Spacing token
+<IressPanel p="lg">Content</IressPanel>
+```
+
+### ❌ DON'T: Use inline styles for spacing
+
+Inline styles bypass the design system and make code non-themeable.
+
+```tsx
+// ❌ INCORRECT - Inline styles
+<IressPanel style={{ margin: '16px 0', padding: '8px 24px' }}>
+  Content
+</IressPanel>
+
+// ✅ CORRECT - Styling props with tokens
+<IressPanel my="md" px="lg" py="sm">
+  Content
+</IressPanel>
+```
+
+### ✅ DO: Use `cssVars` for CSS-in-JS
+
+If you're using a CSS-in-JS library, use `cssVars` from `@iress-oss/ids-tokens` to reference spacing tokens.
+
+```tsx
+
+// ✅ CORRECT - Using cssVars for spacing in CSS-in-JS
+const StyledPanel = styled.div`
+  padding: ${cssVars.spacing[10]}; /* xl - 40px */
+  margin: ${cssVars.spacing[4]} 0; /* md - 16px vertical */
+  gap: ${cssVars.spacing[2]}; /* sm - 8px */
+`;
+
+// ✅ CORRECT - Directional spacing
+const StyledBox = styled.div`
+  padding-left: ${cssVars.spacing[6]}; /* lg - 24px */
+  padding-right: ${cssVars.spacing[6]};
+  padding-top: ${cssVars.spacing[2]}; /* sm - 8px */
+  padding-bottom: ${cssVars.spacing[2]};
+`;
+```
+
+### ❌ DON'T: Use arbitrary values - stick to the spacing scale
+
+The spacing scale is designed to create visual consistency. Avoid arbitrary values that don't fit the scale.
+
+```tsx
+// ❌ INCORRECT - Arbitrary spacing value
+<IressPanel style={{ padding: '17px' }}>Content</IressPanel>
+
+// ✅ CORRECT - Use the closest value from the scale
+<IressPanel p="md">Content (16px)</IressPanel>
+
+// ✅ ALSO CORRECT - If you need more, use the next step
+<IressPanel p="lg">Content (24px)</IressPanel>
+```
+
+## Token Reference
+
+For a complete reference of the full spacing scale with all available tokens (spacing.0 through spacing.10), visual examples, and pixel values, see the documentation.
+
+**Quick reference - Most commonly used spacing tokens:**
+
+- `spacing.1` / `xs`: 4px - Extra small spacing
+- `spacing.2` / `sm`: 8px - Small spacing
+- `spacing.4` / `md`: 16px - Medium spacing (default for many components)
+- `spacing.6` / `lg`: 24px - Large spacing
+- `spacing.10` / `xl`: 40px - Extra large spacing
+
+[View Full Spacing Token Reference](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/tokens_spacing--docs)
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-spacing--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-spacing--docs)*

package/.ai/guides/styling-props-typography.md

@@ -0,0 +1,153 @@
+# Typography
+
+> **Guide:** `@iress-oss/ids-components`
+> **Storybook:** [Typography in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-typography--docs)
+
+These are all styling props related to changing the typography of a component.
+
+## `textStyle`
+
+The `textStyle` prop allows you to change the default text style of a component. For more control and nested element styling, it is recommended to use `IressText` instead.
+
+```tsx
+<IressTypography bg="alt" textStyle="typography.heading.5">
+  A panel with large text
+</IressTypography>
+```
+
+[View "textStyle" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-typography--text-style)
+
+## `textAlign`
+
+The `textAlign` prop allows you to change the alignment of text inside a component. For more control, it is recommended to use `IressText` instead.
+
+```tsx
+<IressTypography bg="alt" textAlign="center">
+  A panel with centered text
+</IressTypography>
+```
+
+[View "textAlign" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_styling-props-typography--text-align)
+
+---
+
+## Best Practices
+
+For typography, the **IressText component is the preferred approach** for most use cases. It provides semantic HTML elements, accessibility features, and proper text styling out of the box.
+
+### ✅ DO (PREFERRED): Use the `IressText` component
+
+The `IressText` component is the recommended way to render text content. It handles typography tokens automatically and provides semantic HTML elements.
+
+```tsx
+// ✅ CORRECT - Use IressText (recommended)
+<IressText>Default body text with proper styling</IressText>
+
+<IressText element="h1">Heading rendered as h1 element</IressText>
+```
+
+**Why use IressText:**
+
+- Provides semantic HTML elements (`h1`, `h2`, `p`, `span`, etc.)
+- Handles typography tokens automatically
+- Ensures accessibility with proper heading hierarchy
+- No need to manage font properties manually
+
+### ✅ DO (ALTERNATIVE): Use `textStyle` prop with typography tokens
+
+When you need to apply typography styling to components that aren't text-specific (like `IressPanel`), use the `textStyle` prop with typography tokens.
+
+```tsx
+// ✅ CORRECT - Using textStyle prop with tokens
+<IressPanel textStyle="typography.heading.1">
+  Panel with heading-sized text
+</IressPanel>
+```
+
+**Available typography tokens:**
+
+- `typography.body.sm`, `typography.body.md` - Body text variants
+- `typography.heading.1`, `typography.heading.2`, `typography.heading.3` - Heading text variants
+
+### ❌ DON'T: Use inline styles for typography
+
+Inline styles with hardcoded font properties bypass the design system and don't respond to typography token updates.
+
+```tsx
+// ❌ INCORRECT - Hardcoded typography
+<h1 style={{ fontSize: '24px', fontWeight: 'bold', lineHeight: '1.2' }}>
+  Heading
+</h1>
+
+<p style={{ fontSize: '16px', fontFamily: 'Arial' }}>
+  Body text
+</p>
+
+// ✅ CORRECT - Use IressText
+<IressText element="h1">Heading</IressText>
+
+<IressText>Body text</IressText>
+```
+
+### ✅ DO: Use `cssVars` for CSS-in-JS
+
+If you're using a CSS-in-JS library, use `cssVars` from `@iress-oss/ids-tokens` to reference typography tokens.
+
+```tsx
+
+// ✅ CORRECT - Using cssVars for typography in CSS-in-JS
+const Heading = styled.h1`
+  font: ${cssVars.typography.heading[1]};
+`;
+
+const BodyText = styled.p`
+  font: ${cssVars.typography.md.regular};
+`;
+```
+
+### ❌ DON'T: Use hardcoded font properties
+
+Hardcoded font sizes, weights, and families don't adapt to design system changes and break consistency.
+
+```tsx
+// ❌ INCORRECT - Hardcoded font properties
+<div style={{
+  fontSize: '16px',
+  fontWeight: '600',
+  fontFamily: 'Inter, sans-serif'
+}}>
+  Content
+</div>
+
+// ✅ CORRECT - Use textStyle prop with token
+<IressPanel textStyle="typography.body.md">
+  Content
+</IressPanel>
+```
+
+### When to use IressText vs textStyle prop
+
+**Use `IressText` when:**
+
+- Rendering text content (paragraphs, headings, labels)
+- You need semantic HTML elements
+- Building accessible content with proper heading hierarchy
+- Creating text-focused UI components
+
+**Use `textStyle` prop when:**
+
+- Applying typography styling to non-text components
+- You already have a component and just need text styling
+- Working with layout components like `IressPanel` or `IressStack`
+
+## Token Reference
+
+For a complete reference of all available typography tokens with font families, sizes, weights, and line heights, see the documentation.
+
+Typography tokens include font family, size, weight, and line height specifications
+
+[View Full Typography Token Reference](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/tokens_typography--docs)
+
+---
+
+*View in Storybook: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-typography--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_styling-props-typography--docs)*