@lunar-js/lunar 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @lunar-js/lunar
 
+## 0.1.0 (2026-01-07)
+
+### Added
+
+- add visually hidden style utility -
+  [`b072927`](https://github.com/lunar-js/lunar/commit/b0729275b5ddf45aff1b151c16e1ea287c189689) Thanks astronaut
+  [@prests](https://github.com/prests)!
+
 ## 0.0.3 (2025-11-30)
 
 ### Changed

package/dist/components/primitives/Input/input.css.js

@@ -26,7 +26,7 @@ const input = style([
 		color: themeContract.colors.text.primary,
 		selectors: {
 			"&[aria-invalid=\"true\"]": { borderColor: themeContract.colors.border.error },
-			...withCustomOutline(themeContract.colors.shadow.destructive, "&[aria-invalid=\"true\"]")
+			...withCustomOutline(themeContract.colors.shadow.destructive, "&[aria-invalid=\"true\"]:focus-visible")
 		},
 		"::file-selector-button": {
 			display: "inline-flex",

package/dist/components/primitives/Input/input.css.js.map

@@ -1 +1 @@
-{"version":3,"file":"input.css.js","names":[],"sources":["../../../../src/components/primitives/Input/input.css.ts"],"sourcesContent":["import { style } from '@vanilla-extract/css';\n\nimport { themeContract } from '../../../themes/tokens/tokens.css.js';\nimport { withBreakpoint, withCustomOutline, withSafeTransition } from '../../../themes/styles/utilities.js';\nimport { BREAKPOINT__MD } from '../../../constants/theming.js';\nimport { COLORS__PURE } from '../../../themes/tokens/primitives/colors.js';\n\nconst input = style([\n  withBreakpoint(BREAKPOINT__MD, {\n    fontSize: themeContract.typography.body.sm.medium.fontSize,\n  }),\n  withCustomOutline(themeContract.colors.shadow.focus),\n  withSafeTransition({\n    transition: 'color 150ms ease-in-out, box-shadow 150ms ease-in-out',\n  }),\n  {\n    width: '100%',\n    minWidth: 0,\n    boxSizing: 'border-box',\n    borderRadius: themeContract.borderRadius.md,\n    border: `${themeContract.borderWidth[1]} solid ${themeContract.colors.input.border.default}`,\n    backgroundColor: COLORS__PURE.transparent,\n    paddingLeft: themeContract.spacing[3],\n    paddingRight: themeContract.spacing[3],\n    paddingTop: themeContract.spacing[1],\n    paddingBottom: themeContract.spacing[1],\n    fontSize: themeContract.typography.body.md.medium.fontSize,\n    lineHeight: themeContract.typography.body.md.medium.lineHeight,\n    boxShadow: themeContract.boxShadow.sm,\n    color: themeContract.colors.text.primary,\n    selectors: {\n      '&[aria-invalid=\"true\"]': {\n        borderColor: themeContract.colors.border.error,\n      },\n      ...withCustomOutline(themeContract.colors.shadow.destructive, '&[aria-invalid=\"true\"]'),\n    },\n\n    '::file-selector-button': {\n      display: 'inline-flex',\n      border: 0,\n      backgroundColor: COLORS__PURE.transparent,\n      fontSize: themeContract.typography.body.md.medium.fontSize,\n      fontWeight: themeContract.typography.body.md.medium.fontWeight,\n      color: themeContract.colors.text.primary,\n    },\n\n    '::placeholder': {\n      color: themeContract.colors.input.text.placeholder,\n    },\n\n    '::selection': {\n      backgroundColor: themeContract.colors.action.bg.primary.default,\n      color: themeContract.colors.action.color.primary,\n    },\n\n    ':disabled': {\n      pointerEvents: 'none',\n      cursor: 'not-allowed',\n      opacity: '0.5',\n    },\n  },\n]);\n\nexport { input };\n"],"mappings":";;;;;;;AAOA,MAAM,QAAQ,MAAM;CAClB,eAAe,gBAAgB,EAC7B,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO,UACnD,CAAC;CACF,kBAAkB,cAAc,OAAO,OAAO,MAAM;CACpD,mBAAmB,EACjB,YAAY,yDACb,CAAC;CACF;EACE,OAAO;EACP,UAAU;EACV,WAAW;EACX,cAAc,cAAc,aAAa;EACzC,QAAQ,GAAG,cAAc,YAAY,GAAG,SAAS,cAAc,OAAO,MAAM,OAAO;EACnF,iBAAiB,aAAa;EAC9B,aAAa,cAAc,QAAQ;EACnC,cAAc,cAAc,QAAQ;EACpC,YAAY,cAAc,QAAQ;EAClC,eAAe,cAAc,QAAQ;EACrC,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO;EAClD,YAAY,cAAc,WAAW,KAAK,GAAG,OAAO;EACpD,WAAW,cAAc,UAAU;EACnC,OAAO,cAAc,OAAO,KAAK;EACjC,WAAW;GACT,4BAA0B,EACxB,aAAa,cAAc,OAAO,OAAO,OAC1C;GACD,GAAG,kBAAkB,cAAc,OAAO,OAAO,aAAa,2BAAyB;GACxF;EAED,0BAA0B;GACxB,SAAS;GACT,QAAQ;GACR,iBAAiB,aAAa;GAC9B,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO;GAClD,YAAY,cAAc,WAAW,KAAK,GAAG,OAAO;GACpD,OAAO,cAAc,OAAO,KAAK;GAClC;EAED,iBAAiB,EACf,OAAO,cAAc,OAAO,MAAM,KAAK,aACxC;EAED,eAAe;GACb,iBAAiB,cAAc,OAAO,OAAO,GAAG,QAAQ;GACxD,OAAO,cAAc,OAAO,OAAO,MAAM;GAC1C;EAED,aAAa;GACX,eAAe;GACf,QAAQ;GACR,SAAS;GACV;EACF;CACF,CAAC"}
+{"version":3,"file":"input.css.js","names":[],"sources":["../../../../src/components/primitives/Input/input.css.ts"],"sourcesContent":["import { style } from '@vanilla-extract/css';\n\nimport { themeContract } from '../../../themes/tokens/tokens.css.js';\nimport { withBreakpoint, withCustomOutline, withSafeTransition } from '../../../themes/styles/utilities.js';\nimport { BREAKPOINT__MD } from '../../../constants/theming.js';\nimport { COLORS__PURE } from '../../../themes/tokens/primitives/colors.js';\n\nconst input = style([\n  withBreakpoint(BREAKPOINT__MD, {\n    fontSize: themeContract.typography.body.sm.medium.fontSize,\n  }),\n  withCustomOutline(themeContract.colors.shadow.focus),\n  withSafeTransition({\n    transition: 'color 150ms ease-in-out, box-shadow 150ms ease-in-out',\n  }),\n  {\n    width: '100%',\n    minWidth: 0,\n    boxSizing: 'border-box',\n    borderRadius: themeContract.borderRadius.md,\n    border: `${themeContract.borderWidth[1]} solid ${themeContract.colors.input.border.default}`,\n    backgroundColor: COLORS__PURE.transparent,\n    paddingLeft: themeContract.spacing[3],\n    paddingRight: themeContract.spacing[3],\n    paddingTop: themeContract.spacing[1],\n    paddingBottom: themeContract.spacing[1],\n    fontSize: themeContract.typography.body.md.medium.fontSize,\n    lineHeight: themeContract.typography.body.md.medium.lineHeight,\n    boxShadow: themeContract.boxShadow.sm,\n    color: themeContract.colors.text.primary,\n    selectors: {\n      '&[aria-invalid=\"true\"]': {\n        borderColor: themeContract.colors.border.error,\n      },\n      ...withCustomOutline(themeContract.colors.shadow.destructive, '&[aria-invalid=\"true\"]:focus-visible'),\n    },\n\n    '::file-selector-button': {\n      display: 'inline-flex',\n      border: 0,\n      backgroundColor: COLORS__PURE.transparent,\n      fontSize: themeContract.typography.body.md.medium.fontSize,\n      fontWeight: themeContract.typography.body.md.medium.fontWeight,\n      color: themeContract.colors.text.primary,\n    },\n\n    '::placeholder': {\n      color: themeContract.colors.input.text.placeholder,\n    },\n\n    '::selection': {\n      backgroundColor: themeContract.colors.action.bg.primary.default,\n      color: themeContract.colors.action.color.primary,\n    },\n\n    ':disabled': {\n      pointerEvents: 'none',\n      cursor: 'not-allowed',\n      opacity: '0.5',\n    },\n  },\n]);\n\nexport { input };\n"],"mappings":";;;;;;;AAOA,MAAM,QAAQ,MAAM;CAClB,eAAe,gBAAgB,EAC7B,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO,UACnD,CAAC;CACF,kBAAkB,cAAc,OAAO,OAAO,MAAM;CACpD,mBAAmB,EACjB,YAAY,yDACb,CAAC;CACF;EACE,OAAO;EACP,UAAU;EACV,WAAW;EACX,cAAc,cAAc,aAAa;EACzC,QAAQ,GAAG,cAAc,YAAY,GAAG,SAAS,cAAc,OAAO,MAAM,OAAO;EACnF,iBAAiB,aAAa;EAC9B,aAAa,cAAc,QAAQ;EACnC,cAAc,cAAc,QAAQ;EACpC,YAAY,cAAc,QAAQ;EAClC,eAAe,cAAc,QAAQ;EACrC,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO;EAClD,YAAY,cAAc,WAAW,KAAK,GAAG,OAAO;EACpD,WAAW,cAAc,UAAU;EACnC,OAAO,cAAc,OAAO,KAAK;EACjC,WAAW;GACT,4BAA0B,EACxB,aAAa,cAAc,OAAO,OAAO,OAC1C;GACD,GAAG,kBAAkB,cAAc,OAAO,OAAO,aAAa,yCAAuC;GACtG;EAED,0BAA0B;GACxB,SAAS;GACT,QAAQ;GACR,iBAAiB,aAAa;GAC9B,UAAU,cAAc,WAAW,KAAK,GAAG,OAAO;GAClD,YAAY,cAAc,WAAW,KAAK,GAAG,OAAO;GACpD,OAAO,cAAc,OAAO,KAAK;GAClC;EAED,iBAAiB,EACf,OAAO,cAAc,OAAO,MAAM,KAAK,aACxC;EAED,eAAe;GACb,iBAAiB,cAAc,OAAO,OAAO,GAAG,QAAQ;GACxD,OAAO,cAAc,OAAO,OAAO,MAAM;GAC1C;EAED,aAAa;GACX,eAAe;GACf,QAAQ;GACR,SAAS;GACV;EACF;CACF,CAAC"}

package/dist/index.d.ts

@@ -11,10 +11,10 @@ import { Text, TextProps } from "./components/primitives/Typography/Text.js";
 import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./components/composite/Card/Card.js";
 import { Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTrigger } from "./components/composite/Dialog/Dialog.js";
 import { useDialog } from "./hooks/dialog.js";
-import { withBreakpoint, withCustomOutline, withSafeTransition } from "./themes/styles/utilities.js";
+import { withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden } from "./themes/styles/utilities.js";
 import { COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW } from "./themes/tokens/primitives/colors.js";
 import { SPACING } from "./themes/tokens/primitives/spacing.js";
 import { BORDER_RADIUS, BORDER_WIDTH } from "./themes/tokens/primitives/borders.js";
 import { BOX_SHADOW } from "./themes/tokens/primitives/shadows.js";
 import { FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT } from "./themes/tokens/primitives/typography.js";
-export { BORDER_RADIUS, BORDER_WIDTH, BOX_SHADOW, BREAKPOINT__LG, BREAKPOINT__MD, BREAKPOINT__SM, BUTTON_SIZE__LARGE, BUTTON_SIZE__MEDIUM, BUTTON_SIZE__SMALL, BUTTON_VARIANT__DESTRUCTIVE, BUTTON_VARIANT__GHOST, BUTTON_VARIANT__LINK, BUTTON_VARIANT__OUTLINE, BUTTON_VARIANT__PRIMARY, BUTTON_VARIANT__SECONDARY, Button, type ButtonProps, COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW, COLOR_SCHEME__DARK, COLOR_SCHEME__LIGHT, COLOR_SCHEME__SYSTEM, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ColorScheme, Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTrigger, FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, Input, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT, Label, SPACING, TEXT_COLOR__ACCENT, TEXT_COLOR__BRAND, TEXT_COLOR__DANGER, TEXT_COLOR__DISABLED, TEXT_COLOR__INFO, TEXT_COLOR__INTERACTIVE, TEXT_COLOR__INVERSE, TEXT_COLOR__MUTED, TEXT_COLOR__PRIMARY, TEXT_COLOR__SECONDARY, TEXT_COLOR__SUCCESS, TEXT_COLOR__WARNING, TEXT_SIZE__LG, TEXT_SIZE__MD, TEXT_SIZE__SM, TEXT_SIZE__XL, TEXT_VARIANT__BODY, TEXT_VARIANT__CAPTION, TEXT_VARIANT__DISPLAY, TEXT_VARIANT__HEADING, TEXT_VARIANT__LABEL, TEXT_VARIANT__SUBHEADING, TEXT_WEIGHT__BOLD, TEXT_WEIGHT__LIGHT, TEXT_WEIGHT__MEDIUM, Text, type TextProps, ThemeProvider, useDialog, useTheme, withBreakpoint, withCustomOutline, withSafeTransition };
+export { BORDER_RADIUS, BORDER_WIDTH, BOX_SHADOW, BREAKPOINT__LG, BREAKPOINT__MD, BREAKPOINT__SM, BUTTON_SIZE__LARGE, BUTTON_SIZE__MEDIUM, BUTTON_SIZE__SMALL, BUTTON_VARIANT__DESTRUCTIVE, BUTTON_VARIANT__GHOST, BUTTON_VARIANT__LINK, BUTTON_VARIANT__OUTLINE, BUTTON_VARIANT__PRIMARY, BUTTON_VARIANT__SECONDARY, Button, type ButtonProps, COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW, COLOR_SCHEME__DARK, COLOR_SCHEME__LIGHT, COLOR_SCHEME__SYSTEM, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ColorScheme, Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTrigger, FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, Input, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT, Label, SPACING, TEXT_COLOR__ACCENT, TEXT_COLOR__BRAND, TEXT_COLOR__DANGER, TEXT_COLOR__DISABLED, TEXT_COLOR__INFO, TEXT_COLOR__INTERACTIVE, TEXT_COLOR__INVERSE, TEXT_COLOR__MUTED, TEXT_COLOR__PRIMARY, TEXT_COLOR__SECONDARY, TEXT_COLOR__SUCCESS, TEXT_COLOR__WARNING, TEXT_SIZE__LG, TEXT_SIZE__MD, TEXT_SIZE__SM, TEXT_SIZE__XL, TEXT_VARIANT__BODY, TEXT_VARIANT__CAPTION, TEXT_VARIANT__DISPLAY, TEXT_VARIANT__HEADING, TEXT_VARIANT__LABEL, TEXT_VARIANT__SUBHEADING, TEXT_WEIGHT__BOLD, TEXT_WEIGHT__LIGHT, TEXT_WEIGHT__MEDIUM, Text, type TextProps, ThemeProvider, useDialog, useTheme, withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden };

package/dist/index.js

@@ -3,7 +3,7 @@ import ThemeProvider_default from "./themes/ThemeProvider/ThemeProvider.js";
 import { useTheme } from "./hooks/theme.js";
 import { SPACING } from "./themes/tokens/primitives/spacing.js";
 import { COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW } from "./themes/tokens/primitives/colors.js";
-import { withBreakpoint, withCustomOutline, withSafeTransition } from "./themes/styles/utilities.js";
+import { withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden } from "./themes/styles/utilities.js";
 import { BUTTON_SIZE__LARGE, BUTTON_SIZE__MEDIUM, BUTTON_SIZE__SMALL, BUTTON_VARIANT__DESTRUCTIVE, BUTTON_VARIANT__GHOST, BUTTON_VARIANT__LINK, BUTTON_VARIANT__OUTLINE, BUTTON_VARIANT__PRIMARY, BUTTON_VARIANT__SECONDARY } from "./components/primitives/Button/button.css.js";
 import Button_default from "./components/primitives/Button/Button.js";
 import Input_default from "./components/primitives/Input/Input.js";
@@ -17,4 +17,4 @@ import { BORDER_RADIUS, BORDER_WIDTH } from "./themes/tokens/primitives/borders.
 import { BOX_SHADOW } from "./themes/tokens/primitives/shadows.js";
 import { FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT } from "./themes/tokens/primitives/typography.js";
 
-export { BORDER_RADIUS, BORDER_WIDTH, BOX_SHADOW, BREAKPOINT__LG, BREAKPOINT__MD, BREAKPOINT__SM, BUTTON_SIZE__LARGE, BUTTON_SIZE__MEDIUM, BUTTON_SIZE__SMALL, BUTTON_VARIANT__DESTRUCTIVE, BUTTON_VARIANT__GHOST, BUTTON_VARIANT__LINK, BUTTON_VARIANT__OUTLINE, BUTTON_VARIANT__PRIMARY, BUTTON_VARIANT__SECONDARY, Button_default as Button, COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW, COLOR_SCHEME__DARK, COLOR_SCHEME__LIGHT, COLOR_SCHEME__SYSTEM, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTrigger, FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, Input_default as Input, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT, Label_default as Label, SPACING, TEXT_COLOR__ACCENT, TEXT_COLOR__BRAND, TEXT_COLOR__DANGER, TEXT_COLOR__DISABLED, TEXT_COLOR__INFO, TEXT_COLOR__INTERACTIVE, TEXT_COLOR__INVERSE, TEXT_COLOR__MUTED, TEXT_COLOR__PRIMARY, TEXT_COLOR__SECONDARY, TEXT_COLOR__SUCCESS, TEXT_COLOR__WARNING, TEXT_SIZE__LG, TEXT_SIZE__MD, TEXT_SIZE__SM, TEXT_SIZE__XL, TEXT_VARIANT__BODY, TEXT_VARIANT__CAPTION, TEXT_VARIANT__DISPLAY, TEXT_VARIANT__HEADING, TEXT_VARIANT__LABEL, TEXT_VARIANT__SUBHEADING, TEXT_WEIGHT__BOLD, TEXT_WEIGHT__LIGHT, TEXT_WEIGHT__MEDIUM, Text_default as Text, ThemeProvider_default as ThemeProvider, useDialog, useTheme, withBreakpoint, withCustomOutline, withSafeTransition };
+export { BORDER_RADIUS, BORDER_WIDTH, BOX_SHADOW, BREAKPOINT__LG, BREAKPOINT__MD, BREAKPOINT__SM, BUTTON_SIZE__LARGE, BUTTON_SIZE__MEDIUM, BUTTON_SIZE__SMALL, BUTTON_VARIANT__DESTRUCTIVE, BUTTON_VARIANT__GHOST, BUTTON_VARIANT__LINK, BUTTON_VARIANT__OUTLINE, BUTTON_VARIANT__PRIMARY, BUTTON_VARIANT__SECONDARY, Button_default as Button, COLORS__BLUE, COLORS__GOLD, COLORS__GREEN, COLORS__PEARL, COLORS__PURE, COLORS__RED, COLORS__STONE, COLORS__YELLOW, COLOR_SCHEME__DARK, COLOR_SCHEME__LIGHT, COLOR_SCHEME__SYSTEM, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTrigger, FONT_FAMILY, FONT_SIZE, FONT_WEIGHT, Input_default as Input, LETTER_SPACING, LINE_HEIGHT__RELAXED, LINE_HEIGHT__TIGHT, Label_default as Label, SPACING, TEXT_COLOR__ACCENT, TEXT_COLOR__BRAND, TEXT_COLOR__DANGER, TEXT_COLOR__DISABLED, TEXT_COLOR__INFO, TEXT_COLOR__INTERACTIVE, TEXT_COLOR__INVERSE, TEXT_COLOR__MUTED, TEXT_COLOR__PRIMARY, TEXT_COLOR__SECONDARY, TEXT_COLOR__SUCCESS, TEXT_COLOR__WARNING, TEXT_SIZE__LG, TEXT_SIZE__MD, TEXT_SIZE__SM, TEXT_SIZE__XL, TEXT_VARIANT__BODY, TEXT_VARIANT__CAPTION, TEXT_VARIANT__DISPLAY, TEXT_VARIANT__HEADING, TEXT_VARIANT__LABEL, TEXT_VARIANT__SUBHEADING, TEXT_WEIGHT__BOLD, TEXT_WEIGHT__LIGHT, TEXT_WEIGHT__MEDIUM, Text_default as Text, ThemeProvider_default as ThemeProvider, useDialog, useTheme, withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden };

package/dist/themes/styles/utilities.d.ts

@@ -30,14 +30,10 @@ import { CSSProperties, StyleRule } from "@vanilla-extract/css";
 declare const withSafeTransition: (styles: StyleRule) => StyleRule;
 /**
  * Helper function to create a custom focus outline style object.
- * Returns a style object with focus-visible outline that follows the design system's outline pattern.
- * Supports an optional selector parameter for targeting specific pseudo-selectors or child elements.
- *
- * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
  *
  * @param outlineColor - The color for the focus outline (e.g., '#0066cc', 'rgb(255, 0, 0)', CSS custom properties)
- * @param selector - Optional selector prefix for the focus-visible state (e.g., '&', '& > button', defaults to '')
- * @returns A style object with custom focus outline styling that uses dynamic selector keys
+ * @param selector - Optional CSS selector for the outline state (e.g., ':focus-visible', '&:hover', '& > button:focus-visible', defaults to ':focus-visible')
+ * @returns A style object with custom focus outline styling that uses the provided selector
  *
  * @example
  * import { style } from '@vanilla-extract/css';
@@ -53,10 +49,11 @@ declare const withSafeTransition: (styles: StyleRule) => StyleRule;
  * ]);
  *
  * // Example with custom selector
- * const parentWithFocusableChild = style([
- *   withCustomOutline('#0066cc', '& > button'),
+ * const hoverOutlineButton = style([
+ *   withCustomOutline('#00cc66', ':hover'),
  *   {
- *     padding: '12px'
+ *     padding: '8px 16px',
+ *     background: 'white'
  *   }
  * ]);
  *
@@ -73,13 +70,9 @@ declare const withSafeTransition: (styles: StyleRule) => StyleRule;
  *   }
  * });
  */
-declare const withCustomOutline: (outlineColor: string, selector?: string) => Record<`${string}:focus-visible`, CSSProperties>;
+declare const withCustomOutline: (outlineColor: string, selector?: string) => Record<string, CSSProperties>;
 /**
  * Helper function to create a responsive style object with breakpoint media queries.
- * Returns a style object that applies the provided styles only when the viewport width
- * meets or exceeds the specified breakpoint value.
- *
- * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
  *
  * @param breakpoint - The minimum viewport width for the media query (e.g., '768px', '1024px', '48rem')
  * @param styles - CSS properties object to apply at the breakpoint (e.g., { fontSize: '1.5rem', padding: '24px' })
@@ -120,6 +113,45 @@ declare const withCustomOutline: (outlineColor: string, selector?: string) => Re
  * });
  */
 declare const withBreakpoint: (breakpoint: string, styles: CSSProperties) => StyleRule;
+/**
+ * Helper function to create a visually hidden style object for screen reader accessibility.
+ * Returns a style object that hides content visually while keeping it accessible to screen readers.
+ * This is useful for providing descriptive text, skip links, or other content that should only
+ * be available to assistive technologies.
+ *
+ * @returns A style object that visually hides content while maintaining screen reader accessibility
+ *
+ * @example
+ * import { style } from '@vanilla-extract/css';
+ * import { recipe } from '@vanilla-extract/recipes';
+ * import { withVisuallyHidden } from './utilities.css.ts';
+ *
+ * const skipLink = style([
+ *   withVisuallyHidden(),
+ *   {
+ *     // Additional styles can be added here
+ *     zIndex: 1000
+ *   }
+ * ]);
+ *
+ * const srOnly = style([
+ *   withVisuallyHidden()
+ * ]);
+ *
+ * const buttonWithHiddenText = recipe({
+ *   base: [
+ *     withVisuallyHidden(),
+ *     {
+ *       padding: '8px 12px',
+ *       background: 'blue'
+ *     }
+ *   ],
+ *   variants: {
+ *     // variant styles
+ *   }
+ * });
+ */
+declare const withVisuallyHidden: () => StyleRule;
 //#endregion
-export { withBreakpoint, withCustomOutline, withSafeTransition };
+export { withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden };
 //# sourceMappingURL=utilities.d.ts.map

package/dist/themes/styles/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","names":[],"sources":["../../../src/themes/styles/utilities.ts"],"sourcesContent":[],"mappings":";;;;;;AAA0E;;;;;AAiCxE;;;;;AA+CqE;;;;;;;;;;;;;cAnDjE,6BAA8B,cAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmD1C,gEAA2D,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqD7F,6CAA8C,kBAAgB"}
+{"version":3,"file":"utilities.d.ts","names":[],"sources":["../../../src/themes/styles/utilities.ts"],"sourcesContent":[],"mappings":";;;;;;AAA0E;;;;;AAiCxE;;;;;AA4CmF;;;;;AAqDnF;;;;;;;;cArGI,6BAA8B,cAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgD1C,gEAAyE,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiDxF,6CAA8C,kBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4C9D,0BAAyB"}

package/dist/themes/styles/utilities.js

@@ -29,14 +29,10 @@ import { COLORS__PURE } from "../tokens/primitives/colors.js";
 const withSafeTransition = (styles) => ({ "@media": { "(prefers-reduced-motion: no-preference)": styles } });
 /**
 * Helper function to create a custom focus outline style object.
-* Returns a style object with focus-visible outline that follows the design system's outline pattern.
-* Supports an optional selector parameter for targeting specific pseudo-selectors or child elements.
-*
-* This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
 *
 * @param outlineColor - The color for the focus outline (e.g., '#0066cc', 'rgb(255, 0, 0)', CSS custom properties)
-* @param selector - Optional selector prefix for the focus-visible state (e.g., '&', '& > button', defaults to '')
-* @returns A style object with custom focus outline styling that uses dynamic selector keys
+* @param selector - Optional CSS selector for the outline state (e.g., ':focus-visible', '&:hover', '& > button:focus-visible', defaults to ':focus-visible')
+* @returns A style object with custom focus outline styling that uses the provided selector
 *
 * @example
 * import { style } from '@vanilla-extract/css';
@@ -52,10 +48,11 @@ const withSafeTransition = (styles) => ({ "@media": { "(prefers-reduced-motion:
 * ]);
 *
 * // Example with custom selector
-* const parentWithFocusableChild = style([
-*   withCustomOutline('#0066cc', '& > button'),
+* const hoverOutlineButton = style([
+*   withCustomOutline('#00cc66', ':hover'),
 *   {
-*     padding: '12px'
+*     padding: '8px 16px',
+*     background: 'white'
 *   }
 * ]);
 *
@@ -72,17 +69,13 @@ const withSafeTransition = (styles) => ({ "@media": { "(prefers-reduced-motion:
 *   }
 * });
 */
-const withCustomOutline = (outlineColor, selector = "") => ({ [`${selector}:focus-visible`]: {
+const withCustomOutline = (outlineColor, selector = ":focus-visible") => ({ [selector]: {
 	boxShadow: `0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${outlineColor} 0px 0px 0px 3px, ${outlineColor} 0px 1px 2px 0px`,
 	outline: "2px solid transparent",
 	outlineOffset: "2px"
 } });
 /**
 * Helper function to create a responsive style object with breakpoint media queries.
-* Returns a style object that applies the provided styles only when the viewport width
-* meets or exceeds the specified breakpoint value.
-*
-* This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
 *
 * @param breakpoint - The minimum viewport width for the media query (e.g., '768px', '1024px', '48rem')
 * @param styles - CSS properties object to apply at the breakpoint (e.g., { fontSize: '1.5rem', padding: '24px' })
@@ -123,7 +116,56 @@ const withCustomOutline = (outlineColor, selector = "") => ({ [`${selector}:focu
 * });
 */
 const withBreakpoint = (breakpoint, styles) => ({ "@media": { [`(min-width: ${breakpoint})`]: styles } });
+/**
+* Helper function to create a visually hidden style object for screen reader accessibility.
+* Returns a style object that hides content visually while keeping it accessible to screen readers.
+* This is useful for providing descriptive text, skip links, or other content that should only
+* be available to assistive technologies.
+*
+* @returns A style object that visually hides content while maintaining screen reader accessibility
+*
+* @example
+* import { style } from '@vanilla-extract/css';
+* import { recipe } from '@vanilla-extract/recipes';
+* import { withVisuallyHidden } from './utilities.css.ts';
+*
+* const skipLink = style([
+*   withVisuallyHidden(),
+*   {
+*     // Additional styles can be added here
+*     zIndex: 1000
+*   }
+* ]);
+*
+* const srOnly = style([
+*   withVisuallyHidden()
+* ]);
+*
+* const buttonWithHiddenText = recipe({
+*   base: [
+*     withVisuallyHidden(),
+*     {
+*       padding: '8px 12px',
+*       background: 'blue'
+*     }
+*   ],
+*   variants: {
+*     // variant styles
+*   }
+* });
+*/
+const withVisuallyHidden = () => ({
+	position: "absolute",
+	width: "1px",
+	height: "1px",
+	padding: "0",
+	margin: "-1px",
+	overflow: "hidden",
+	clip: "rect(0, 0, 0, 0)",
+	whiteSpace: "nowrap",
+	borderWidth: "0"
+});
 
 //#endregion
-export { withBreakpoint, withCustomOutline, withSafeTransition };
+export { withBreakpoint, withCustomOutline, withSafeTransition, withVisuallyHidden };
 //# sourceMappingURL=utilities.js.map

package/dist/themes/styles/utilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","names":[],"sources":["../../../src/themes/styles/utilities.ts"],"sourcesContent":["import { type CSSProperties, type StyleRule } from '@vanilla-extract/css';\n\nimport { COLORS__PURE } from '../tokens/primitives/colors.js';\n\n/**\n * Helper function to create a motion-safe style object with custom CSS properties.\n * Returns a style object that wraps the provided styles in a `prefers-reduced-motion: no-preference` media query,\n * ensuring animations only run when users haven't requested reduced motion.\n *\n * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.\n *\n * @param styles - CSS properties object (e.g., { transition: 'opacity 0.3s ease', transform: 'scale(1.1)' })\n * @returns A style object that applies the CSS properties only when motion is preferred\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { withSafeTransition } from './utilities.css.ts';\n *\n * const fadeTransition = style([\n *   withSafeTransition({\n *     transition: 'transform 0.2s ease-out, opacity 0.2s ease-out',\n *     transform: 'translateY(0)'\n *   }),\n *   {\n *     // Additional styles can be added here\n *     padding: '16px'\n *   }\n * ]);\n */\nconst withSafeTransition = (styles: StyleRule): StyleRule => ({\n  '@media': {\n    '(prefers-reduced-motion: no-preference)': styles,\n  },\n});\n\n/**\n * Helper function to create a custom focus outline style object.\n * Returns a style object with focus-visible outline that follows the design system's outline pattern.\n * Supports an optional selector parameter for targeting specific pseudo-selectors or child elements.\n *\n * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.\n *\n * @param outlineColor - The color for the focus outline (e.g., '#0066cc', 'rgb(255, 0, 0)', CSS custom properties)\n * @param selector - Optional selector prefix for the focus-visible state (e.g., '&', '& > button', defaults to '')\n * @returns A style object with custom focus outline styling that uses dynamic selector keys\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { recipe } from '@vanilla-extract/recipes';\n * import { withCustomOutline } from './utilities.css.ts';\n *\n * const redOutlineButton = style([\n *   withCustomOutline('#ff0000'),\n *   {\n *     padding: '8px 16px',\n *     background: 'white'\n *   }\n * ]);\n *\n * // Example with custom selector\n * const parentWithFocusableChild = style([\n *   withCustomOutline('#0066cc', '& > button'),\n *   {\n *     padding: '12px'\n *   }\n * ]);\n *\n * const buttonVariants = recipe({\n *   base: [\n *     withCustomOutline(themeContract.colors.shadow.interactive),\n *     {\n *       // other base styles\n *       padding: '12px 24px'\n *     }\n *   ],\n *   variants: {\n *     // variant styles\n *   }\n * });\n */\nconst withCustomOutline = (outlineColor: string, selector = ''): Record<`${string}:focus-visible`, CSSProperties> => ({\n  [`${selector}:focus-visible`]: {\n    boxShadow: `0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${outlineColor} 0px 0px 0px 3px, ${outlineColor} 0px 1px 2px 0px`,\n    outline: '2px solid transparent',\n    outlineOffset: '2px',\n  },\n});\n\n/**\n * Helper function to create a responsive style object with breakpoint media queries.\n * Returns a style object that applies the provided styles only when the viewport width\n * meets or exceeds the specified breakpoint value.\n *\n * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.\n *\n * @param breakpoint - The minimum viewport width for the media query (e.g., '768px', '1024px', '48rem')\n * @param styles - CSS properties object to apply at the breakpoint (e.g., { fontSize: '1.5rem', padding: '24px' })\n * @returns A style object that applies the CSS properties only when the viewport width meets the breakpoint\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { recipe } from '@vanilla-extract/recipes';\n * import { withBreakpoint } from './utilities.css.ts';\n *\n * const responsiveText = style([\n *   withBreakpoint('768px', {\n *     fontSize: '1.5rem',\n *     lineHeight: '1.4'\n *   }),\n *   {\n *     // Base styles\n *     fontSize: '1rem',\n *     lineHeight: '1.6'\n *   }\n * ]);\n *\n * const cardVariants = recipe({\n *   base: [\n *     withBreakpoint('1024px', {\n *       padding: '32px',\n *       maxWidth: '800px'\n *     }),\n *     {\n *       // base styles\n *       padding: '16px',\n *       maxWidth: '100%'\n *     }\n *   ],\n *   variants: {\n *     // variant styles\n *   }\n * });\n */\nconst withBreakpoint = (breakpoint: string, styles: CSSProperties): StyleRule => ({\n  '@media': {\n    [`(min-width: ${breakpoint})`]: styles,\n  },\n});\n\nexport { withSafeTransition, withCustomOutline, withBreakpoint };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAM,sBAAsB,YAAkC,EAC5D,UAAU,EACR,2CAA2C,QAC5C,EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CD,MAAM,qBAAqB,cAAsB,WAAW,QAA0D,GACnH,GAAG,SAAS,kBAAkB;CAC7B,WAAW,oBAAoB,aAAa,YAAY,oBAAoB,aAAa,YAAY,oBAAoB,aAAa,oBAAoB,aAAa;CACvK,SAAS;CACT,eAAe;CAChB,EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CD,MAAM,kBAAkB,YAAoB,YAAsC,EAChF,UAAU,GACP,eAAe,WAAW,KAAK,QACjC,EACF"}
+{"version":3,"file":"utilities.js","names":[],"sources":["../../../src/themes/styles/utilities.ts"],"sourcesContent":["import { type CSSProperties, type StyleRule } from '@vanilla-extract/css';\n\nimport { COLORS__PURE } from '../tokens/primitives/colors.js';\n\n/**\n * Helper function to create a motion-safe style object with custom CSS properties.\n * Returns a style object that wraps the provided styles in a `prefers-reduced-motion: no-preference` media query,\n * ensuring animations only run when users haven't requested reduced motion.\n *\n * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.\n *\n * @param styles - CSS properties object (e.g., { transition: 'opacity 0.3s ease', transform: 'scale(1.1)' })\n * @returns A style object that applies the CSS properties only when motion is preferred\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { withSafeTransition } from './utilities.css.ts';\n *\n * const fadeTransition = style([\n *   withSafeTransition({\n *     transition: 'transform 0.2s ease-out, opacity 0.2s ease-out',\n *     transform: 'translateY(0)'\n *   }),\n *   {\n *     // Additional styles can be added here\n *     padding: '16px'\n *   }\n * ]);\n */\nconst withSafeTransition = (styles: StyleRule): StyleRule => ({\n  '@media': {\n    '(prefers-reduced-motion: no-preference)': styles,\n  },\n});\n\n/**\n * Helper function to create a custom focus outline style object.\n *\n * @param outlineColor - The color for the focus outline (e.g., '#0066cc', 'rgb(255, 0, 0)', CSS custom properties)\n * @param selector - Optional CSS selector for the outline state (e.g., ':focus-visible', '&:hover', '& > button:focus-visible', defaults to ':focus-visible')\n * @returns A style object with custom focus outline styling that uses the provided selector\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { recipe } from '@vanilla-extract/recipes';\n * import { withCustomOutline } from './utilities.css.ts';\n *\n * const redOutlineButton = style([\n *   withCustomOutline('#ff0000'),\n *   {\n *     padding: '8px 16px',\n *     background: 'white'\n *   }\n * ]);\n *\n * // Example with custom selector\n * const hoverOutlineButton = style([\n *   withCustomOutline('#00cc66', ':hover'),\n *   {\n *     padding: '8px 16px',\n *     background: 'white'\n *   }\n * ]);\n *\n * const buttonVariants = recipe({\n *   base: [\n *     withCustomOutline(themeContract.colors.shadow.interactive),\n *     {\n *       // other base styles\n *       padding: '12px 24px'\n *     }\n *   ],\n *   variants: {\n *     // variant styles\n *   }\n * });\n */\nconst withCustomOutline = (outlineColor: string, selector = ':focus-visible'): Record<string, CSSProperties> => ({\n  [selector]: {\n    boxShadow: `0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${outlineColor} 0px 0px 0px 3px, ${outlineColor} 0px 1px 2px 0px`,\n    outline: '2px solid transparent',\n    outlineOffset: '2px',\n  },\n});\n\n/**\n * Helper function to create a responsive style object with breakpoint media queries.\n *\n * @param breakpoint - The minimum viewport width for the media query (e.g., '768px', '1024px', '48rem')\n * @param styles - CSS properties object to apply at the breakpoint (e.g., { fontSize: '1.5rem', padding: '24px' })\n * @returns A style object that applies the CSS properties only when the viewport width meets the breakpoint\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { recipe } from '@vanilla-extract/recipes';\n * import { withBreakpoint } from './utilities.css.ts';\n *\n * const responsiveText = style([\n *   withBreakpoint('768px', {\n *     fontSize: '1.5rem',\n *     lineHeight: '1.4'\n *   }),\n *   {\n *     // Base styles\n *     fontSize: '1rem',\n *     lineHeight: '1.6'\n *   }\n * ]);\n *\n * const cardVariants = recipe({\n *   base: [\n *     withBreakpoint('1024px', {\n *       padding: '32px',\n *       maxWidth: '800px'\n *     }),\n *     {\n *       // base styles\n *       padding: '16px',\n *       maxWidth: '100%'\n *     }\n *   ],\n *   variants: {\n *     // variant styles\n *   }\n * });\n */\nconst withBreakpoint = (breakpoint: string, styles: CSSProperties): StyleRule => ({\n  '@media': {\n    [`(min-width: ${breakpoint})`]: styles,\n  },\n});\n\n/**\n * Helper function to create a visually hidden style object for screen reader accessibility.\n * Returns a style object that hides content visually while keeping it accessible to screen readers.\n * This is useful for providing descriptive text, skip links, or other content that should only\n * be available to assistive technologies.\n *\n * @returns A style object that visually hides content while maintaining screen reader accessibility\n *\n * @example\n * import { style } from '@vanilla-extract/css';\n * import { recipe } from '@vanilla-extract/recipes';\n * import { withVisuallyHidden } from './utilities.css.ts';\n *\n * const skipLink = style([\n *   withVisuallyHidden(),\n *   {\n *     // Additional styles can be added here\n *     zIndex: 1000\n *   }\n * ]);\n *\n * const srOnly = style([\n *   withVisuallyHidden()\n * ]);\n *\n * const buttonWithHiddenText = recipe({\n *   base: [\n *     withVisuallyHidden(),\n *     {\n *       padding: '8px 12px',\n *       background: 'blue'\n *     }\n *   ],\n *   variants: {\n *     // variant styles\n *   }\n * });\n */\nconst withVisuallyHidden = (): StyleRule => ({\n  position: 'absolute',\n  width: '1px',\n  height: '1px',\n  padding: '0',\n  margin: '-1px',\n  overflow: 'hidden',\n  clip: 'rect(0, 0, 0, 0)',\n  whiteSpace: 'nowrap',\n  borderWidth: '0',\n});\n\nexport { withSafeTransition, withCustomOutline, withBreakpoint, withVisuallyHidden };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAM,sBAAsB,YAAkC,EAC5D,UAAU,EACR,2CAA2C,QAC5C,EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CD,MAAM,qBAAqB,cAAsB,WAAW,sBAAqD,GAC9G,WAAW;CACV,WAAW,oBAAoB,aAAa,YAAY,oBAAoB,aAAa,YAAY,oBAAoB,aAAa,oBAAoB,aAAa;CACvK,SAAS;CACT,eAAe;CAChB,EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CD,MAAM,kBAAkB,YAAoB,YAAsC,EAChF,UAAU,GACP,eAAe,WAAW,KAAK,QACjC,EACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCD,MAAM,4BAAuC;CAC3C,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CACT,QAAQ;CACR,UAAU;CACV,MAAM;CACN,YAAY;CACZ,aAAa;CACd"}

package/package.json

@@ -9,7 +9,7 @@
     "directory": "packages/lunar"
   },
   "homepage": "https://github.com/lunar-js/lunar/tree/main/packages/lunar#readme",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",

package/src/components/primitives/Input/input.css.ts

@@ -32,7 +32,7 @@ const input = style([
       '&[aria-invalid="true"]': {
         borderColor: themeContract.colors.border.error,
       },
-      ...withCustomOutline(themeContract.colors.shadow.destructive, '&[aria-invalid="true"]'),
+      ...withCustomOutline(themeContract.colors.shadow.destructive, '&[aria-invalid="true"]:focus-visible'),
     },
 
     '::file-selector-button': {

package/src/index.ts

@@ -83,7 +83,12 @@ export { useDialog } from './hooks/dialog.js';
 /**
  * Styling Utility Exports
  */
-export { withCustomOutline, withSafeTransition, withBreakpoint } from './themes/styles/utilities.js';
+export {
+  withCustomOutline,
+  withSafeTransition,
+  withBreakpoint,
+  withVisuallyHidden,
+} from './themes/styles/utilities.js';
 
 export { BREAKPOINT__SM, BREAKPOINT__MD, BREAKPOINT__LG } from './constants/theming.js';
 export {

package/src/themes/styles/utilities.ts

@@ -35,14 +35,10 @@ const withSafeTransition = (styles: StyleRule): StyleRule => ({
 
 /**
  * Helper function to create a custom focus outline style object.
- * Returns a style object with focus-visible outline that follows the design system's outline pattern.
- * Supports an optional selector parameter for targeting specific pseudo-selectors or child elements.
- *
- * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
  *
  * @param outlineColor - The color for the focus outline (e.g., '#0066cc', 'rgb(255, 0, 0)', CSS custom properties)
- * @param selector - Optional selector prefix for the focus-visible state (e.g., '&', '& > button', defaults to '')
- * @returns A style object with custom focus outline styling that uses dynamic selector keys
+ * @param selector - Optional CSS selector for the outline state (e.g., ':focus-visible', '&:hover', '& > button:focus-visible', defaults to ':focus-visible')
+ * @returns A style object with custom focus outline styling that uses the provided selector
  *
  * @example
  * import { style } from '@vanilla-extract/css';
@@ -58,10 +54,11 @@ const withSafeTransition = (styles: StyleRule): StyleRule => ({
  * ]);
  *
  * // Example with custom selector
- * const parentWithFocusableChild = style([
- *   withCustomOutline('#0066cc', '& > button'),
+ * const hoverOutlineButton = style([
+ *   withCustomOutline('#00cc66', ':hover'),
  *   {
- *     padding: '12px'
+ *     padding: '8px 16px',
+ *     background: 'white'
  *   }
  * ]);
  *
@@ -78,8 +75,8 @@ const withSafeTransition = (styles: StyleRule): StyleRule => ({
  *   }
  * });
  */
-const withCustomOutline = (outlineColor: string, selector = ''): Record<`${string}:focus-visible`, CSSProperties> => ({
-  [`${selector}:focus-visible`]: {
+const withCustomOutline = (outlineColor: string, selector = ':focus-visible'): Record<string, CSSProperties> => ({
+  [selector]: {
     boxShadow: `0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${COLORS__PURE.transparent} 0px 0px 0px 0px, ${outlineColor} 0px 0px 0px 3px, ${outlineColor} 0px 1px 2px 0px`,
     outline: '2px solid transparent',
     outlineOffset: '2px',
@@ -88,10 +85,6 @@ const withCustomOutline = (outlineColor: string, selector = ''): Record<`${strin
 
 /**
  * Helper function to create a responsive style object with breakpoint media queries.
- * Returns a style object that applies the provided styles only when the viewport width
- * meets or exceeds the specified breakpoint value.
- *
- * This function returns a style object that must be used with vanilla-extract's `style()` function or `recipe()` function.
  *
  * @param breakpoint - The minimum viewport width for the media query (e.g., '768px', '1024px', '48rem')
  * @param styles - CSS properties object to apply at the breakpoint (e.g., { fontSize: '1.5rem', padding: '24px' })
@@ -137,4 +130,54 @@ const withBreakpoint = (breakpoint: string, styles: CSSProperties): StyleRule =>
   },
 });
 
-export { withSafeTransition, withCustomOutline, withBreakpoint };
+/**
+ * Helper function to create a visually hidden style object for screen reader accessibility.
+ * Returns a style object that hides content visually while keeping it accessible to screen readers.
+ * This is useful for providing descriptive text, skip links, or other content that should only
+ * be available to assistive technologies.
+ *
+ * @returns A style object that visually hides content while maintaining screen reader accessibility
+ *
+ * @example
+ * import { style } from '@vanilla-extract/css';
+ * import { recipe } from '@vanilla-extract/recipes';
+ * import { withVisuallyHidden } from './utilities.css.ts';
+ *
+ * const skipLink = style([
+ *   withVisuallyHidden(),
+ *   {
+ *     // Additional styles can be added here
+ *     zIndex: 1000
+ *   }
+ * ]);
+ *
+ * const srOnly = style([
+ *   withVisuallyHidden()
+ * ]);
+ *
+ * const buttonWithHiddenText = recipe({
+ *   base: [
+ *     withVisuallyHidden(),
+ *     {
+ *       padding: '8px 12px',
+ *       background: 'blue'
+ *     }
+ *   ],
+ *   variants: {
+ *     // variant styles
+ *   }
+ * });
+ */
+const withVisuallyHidden = (): StyleRule => ({
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  borderWidth: '0',
+});
+
+export { withSafeTransition, withCustomOutline, withBreakpoint, withVisuallyHidden };