feat(core): enhance dark-aware component with theming

[auswm85]

This pull request introduces a major upgrade to the dark mode awareness system across the documentation and core CSS. The main improvements include support for container-relative theming, perceptual contrast in the OKLCH color space, and visual adaptations such as border glow and font-weight adjustments. Additionally, the documentation and demo components are enhanced to showcase and explain these features, including the ability to preview components in light, dark, or split themes.

Dark Mode Awareness and Theming Enhancements:

• The s-dark-aware utility in functions.css is now a sophisticated system that adapts to both system and parent container themes, computes readable text color using OKLCH, and visually adapts with border glow and dynamic font weight for optimal contrast and legibility. Variants for "subtle" and "strong" adaptations are introduced.
• Documentation for s-dark-aware is expanded to explain the new system, including container-relative theming, perceptual contrast, theme islands, and the technical rationale behind each adaptation. New demos illustrate its behavior in light, dark, and split contexts.

Demo Component and Documentation Improvements:

• The Demo.astro component now accepts a theme prop ('dark' | 'light' | 'split') to force the demo preview into a specific theme or show both light and dark side-by-side. The rendering logic and container classes are updated to support this, enabling accurate previews for theme-aware components.
• New CSS is added to the demo component for split view and theme-specific styling, ensuring that demos accurately reflect their theme context and remain accessible and visually distinct across modes.## Summary

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a theme prop to the Demo component enabling 'dark', 'light', or 'split' previews, expands s-dark-aware documentation with usage and technical details, and implements container-relative theming plus OKLCH-based perceptual contrast and layered dark-mode styles in core CSS.

Changes

Cohort / File(s)	Summary
Demo component apps/docs/src/components/docs/Demo.astro	Adds `theme?: 'dark'
Documentation apps/docs/src/content/docs/utilities/functions.mdx	Replaces brief s-dark-aware note with a comprehensive guide: container-relative theming, OKLCH perceptual contrast, variants (default/subtle/strong), demos, HTML/CSS examples, technical details, and fallback guidance.
Core CSS utilities packages/core/src/utils/functions.css	Introduces container-based theming via [s-theme] and @container queries, multi-layer dark-awareness (prefers-color-scheme baseline, container inheritance, OKLCH color calculations, border glow, font-weight tweaks), variant modifiers, and fallbacks for non-supporting browsers.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(core): add CSS functions and conditional styling utilities #42: Modifies the same documentation page and core CSS utilities file; likely part of the same theming/dark-awareness work.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main enhancement: upgrading the dark-aware component system with theming support.
Description check	✅ Passed	The description provides comprehensive context about the dark mode awareness enhancements, theming system, and demo component improvements, all directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/enhanced-dark-aware

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}