rohanchkrabrty · Oct 18, 2026 · Oct 20, 2026
diff --git a/apps/www/src/content/docs/(overview)/upgrading.mdx b/apps/www/src/content/docs/(overview)/upgrading.mdx
@@ -7,6 +7,29 @@ One section per release, newest first, with only the changes that need action
 from you. The full record of every release, features and fixes included, is
 on [GitHub releases](https://github.com/raystack/apsara/releases).
 
+## Unreleased: `align` takes `start` and `end`
+
+`Headline` and `Container` take `start` and `end` for `align` in place of
+`left` and `right`. Both values follow the text direction. `Headline` already
+aligned its text this way. In a right-to-left layout, `Container` with
+`align="start"` now sits on the right edge, where `align="left"` sat on the
+left. Left-to-right layouts look the same.
+
+| Component | Before | After |
+|---|---|---|
+| `Headline` `align` | `left`, `center`, `right` | `start`, `center`, `end` |
+| `Container` `align` | `left`, `center`, `right` | `start`, `center`, `end` |
+
+```tsx
+// Before
+<Headline align="left">Title</Headline>
+<Container size="small" align="right">...</Container>
+
+// After
+<Headline align="start">Title</Headline>
+<Container size="small" align="end">...</Container>
+```
+
 ## Unreleased: date filters compare whole days
 
 `DataView`, `DataTable` and `FilterChip` read and compare dates as calendar

diff --git a/apps/www/src/content/docs/components/container/demo.ts b/apps/www/src/content/docs/components/container/demo.ts
@@ -19,7 +19,7 @@ export const playground = {
     },
     align: {
       type: 'select',
-      options: ['left', 'center', 'right'],
+      options: ['start', 'center', 'end'],
       defaultValue: 'center'
     },
     children: {
@@ -35,9 +35,9 @@ export const alignDemo = {
   type: 'code',
   tabs: [
     {
-      name: 'Left Aligned',
+      name: 'Start Aligned',
       code: `
-      <Container size="small" align="left">
+      <Container size="small" align="start">
         <Text>
           Workspace settings control how members join, what they can access, and how billing works. Changes apply to everyone in your organization as soon as you save them.
         </Text>
@@ -53,9 +53,9 @@ export const alignDemo = {
       </Container>`
     },
     {
-      name: 'Right Aligned',
+      name: 'End Aligned',
       code: `
-      <Container size="small" align="right">
+      <Container size="small" align="end">
         <Text>
           Workspace settings control how members join, what they can access, and how billing works. Changes apply to everyone in your organization as soon as you save them.
         </Text>

diff --git a/apps/www/src/content/docs/components/container/index.mdx b/apps/www/src/content/docs/components/container/index.mdx
@@ -34,7 +34,7 @@ The `size` prop caps the container's max-width. The default is `none`, which let
 
 ### Align
 
-The `align` prop positions the container within its parent: left, center, or right. Default is `center`.
+The `align` prop positions the container within its parent: `start`, `center`, or `end`. `start` and `end` follow the text direction, so `start` is the right edge in a right-to-left layout. Default is `center`.
 
 <Demo data={alignDemo} />
 

diff --git a/apps/www/src/content/docs/components/container/props.ts b/apps/www/src/content/docs/components/container/props.ts
@@ -10,10 +10,10 @@ export interface ContainerProps {
   size?: 'small' | 'medium' | 'large' | 'none';
 
   /**
-   * Controls the horizontal alignment of the container
+   * Controls the horizontal alignment of the container. `start` and `end` follow the text direction.
    * @defaultValue "center"
    */
-  align?: 'left' | 'center' | 'right';
+  align?: 'start' | 'center' | 'end';
 
   /**
    * Renders the container as a different element.

diff --git a/apps/www/src/content/docs/components/headline/demo.ts b/apps/www/src/content/docs/components/headline/demo.ts
@@ -28,8 +28,8 @@ export const playground = {
     },
     align: {
       type: 'select',
-      options: ['left', 'center', 'right'],
-      defaultValue: 'left',
+      options: ['start', 'center', 'end'],
+      defaultValue: 'start',
       initialValue: 'center'
     },
     truncate: { type: 'checkbox', defaultValue: false },
@@ -42,9 +42,9 @@ export const alignDemo = {
   type: 'code',
   code: `
   <Flex direction="column" style={{width:"100%"}} gap={9}>
-    <Headline size="t2" align="left">Left Aligned</Headline>
+    <Headline size="t2" align="start">Start Aligned</Headline>
     <Headline size="t2" align="center">Center Aligned</Headline>
-    <Headline size="t2" align="right">Right Aligned</Headline>
+    <Headline size="t2" align="end">End Aligned</Headline>
   </Flex>`
 };
 export const truncateDemo = {

diff --git a/apps/www/src/content/docs/components/headline/index.mdx b/apps/www/src/content/docs/components/headline/index.mdx
@@ -34,7 +34,7 @@ Two weights. `medium` is the default; use `regular` where a headline sits close
 
 ### Alignment
 
-`align` sets the text alignment inside the heading's box. Default is `left`.
+`align` sets the text alignment inside the heading's box: `start`, `center`, or `end`. `start` and `end` follow the text direction, so `start` is the right edge in a right-to-left layout. Default is `start`.
 
 <Demo data={alignDemo} />
 

diff --git a/apps/www/src/content/docs/components/headline/props.ts b/apps/www/src/content/docs/components/headline/props.ts
@@ -21,10 +21,10 @@ export interface HeadlineProps {
     | ((props: React.ComponentPropsWithRef<'h2'>) => React.ReactElement);
 
   /**
-   * Text alignment.
-   * @default "left"
+   * Text alignment. `start` and `end` follow the text direction.
+   * @default "start"
    */
-  align?: 'left' | 'center' | 'right';
+  align?: 'start' | 'center' | 'end';
 
   /**
    * Enable text truncation with ellipsis.

diff --git a/packages/react/components/container/__tests__/container.test.tsx b/packages/react/components/container/__tests__/container.test.tsx
@@ -62,20 +62,20 @@ describe('Container', () => {
   });
 
   describe('Alignment', () => {
-    const alignments = ['left', 'center', 'right'] as const;
+    const alignments = ['start', 'center', 'end'] as const;
 
     it.each(alignments)('renders %s alignment correctly', align => {
       const { container: root } = render(
         <Container align={align}>Content</Container>
       );
       const container = root.firstChild as HTMLElement;
-      expect(container).toHaveClass(styles[`container-align-${align}`]);
+      expect(container).toHaveClass(styles[`align-${align}`]);
     });
 
     it('defaults to center alignment', () => {
       const { container: root } = render(<Container>Content</Container>);
       const container = root.firstChild as HTMLElement;
-      expect(container).toHaveClass(styles['container-align-center']);
+      expect(container).toHaveClass(styles['align-center']);
     });
   });
 

diff --git a/packages/react/components/container/container.module.css b/packages/react/components/container/container.module.css
@@ -28,20 +28,16 @@
   max-width: 1145px;
 }
 
-/* Alignment variants */
-.container-align-left {
-  margin-left: 0;
-  margin-right: auto;
+.align-start {
+  margin-inline: 0 auto;
 }
 
-.container-align-center {
-  margin-left: auto;
-  margin-right: auto;
+.align-center {
+  margin-inline: auto;
 }
 
-.container-align-right {
-  margin-left: auto;
-  margin-right: 0;
+.align-end {
+  margin-inline: auto 0;
 }
 
 @media (max-width: 480px) {

diff --git a/packages/react/components/container/container.tsx b/packages/react/components/container/container.tsx
@@ -12,9 +12,9 @@ const container = cva(styles.container, {
       none: styles['container-none']
     },
     align: {
-      left: styles['container-align-left'],
-      center: styles['container-align-center'],
-      right: styles['container-align-right']
+      start: styles['align-start'],
+      center: styles['align-center'],
+      end: styles['align-end']
     }
   },
   defaultVariants: {

diff --git a/packages/react/components/headline/__tests__/headline.test.tsx b/packages/react/components/headline/__tests__/headline.test.tsx
@@ -111,18 +111,18 @@ describe('Headline', () => {
   });
 
   describe('Alignment', () => {
-    const alignments = ['left', 'center', 'right'] as const;
+    const alignments = ['start', 'center', 'end'] as const;
 
     it.each(alignments)('renders %s alignment correctly', align => {
       render(<Headline align={align}>Heading</Headline>);
       const heading = screen.getByText('Heading');
-      expect(heading).toHaveClass(styles[`headline-align-${align}`]);
+      expect(heading).toHaveClass(styles[`align-${align}`]);
     });
 
-    it('defaults to left alignment', () => {
+    it('defaults to start alignment', () => {
       render(<Headline>Heading</Headline>);
       const heading = screen.getByText('Heading');
-      expect(heading).toHaveClass(styles['headline-align-left']);
+      expect(heading).toHaveClass(styles['align-start']);
     });
   });
 

diff --git a/packages/react/components/headline/headline.module.css b/packages/react/components/headline/headline.module.css
@@ -29,15 +29,15 @@
   letter-spacing: var(--rs-letter-spacing-t4);
 }
 
-.headline-align-left {
+.align-start {
   text-align: start;
 }
 
-.headline-align-center {
+.align-center {
   text-align: center;
 }
 
-.headline-align-right {
+.align-end {
   text-align: end;
 }
 

diff --git a/packages/react/components/headline/headline.tsx b/packages/react/components/headline/headline.tsx
@@ -15,9 +15,9 @@ const headline = cva(styles.headline, {
       medium: styles['headline-weight-medium']
     },
     align: {
-      left: styles['headline-align-left'],
-      center: styles['headline-align-center'],
-      right: styles['headline-align-right']
+      start: styles['align-start'],
+      center: styles['align-center'],
+      end: styles['align-end']
     },
     truncate: {
       true: styles['headline-truncate']
@@ -26,7 +26,7 @@ const headline = cva(styles.headline, {
   defaultVariants: {
     size: 't2',
     weight: 'medium',
-    align: 'left',
+    align: 'start',
     truncate: false
   }
 });