app-studio 0.7.10 → 0.7.12

package/README.md

@@ -85,15 +85,76 @@ The `Element` component is the cornerstone of App-Studio. Most other components
 *   **Animation:** Integrates with the animation system via the `animate` prop.
 *   **Theming:** Automatically resolves theme colors (e.g., `color="theme.primary"`).
 
-## Utility-First Styling
+## Styling System
 
+App-Studio uses a powerful, declarative styling system with multiple levels:
+
+### Utility-First Styling
 App-Studio generates CSS utility classes based on the props you provide to `Element` and its derived components. This approach keeps styles co-located with the component logic and optimizes performance by reusing generated classes.
 
-## Theming
+### State Modifiers
+Control styles for interactive states using underscore-prefixed props:
+- **Interaction**: `_hover`, `_active`, `_focus`, `_visited`
+- **Form**: `_disabled`, `_enabled`, `_checked`, `_invalid`, `_valid`
+- **Children**: `_firstChild`, `_lastChild`, `_onlyChild`
+- **Group/Peer**: `_groupHover`, `_peerHover`, `_peerActive`, `_peerChecked`
+- **Pseudo-elements**: `_before`, `_after`, `_firstLetter`, `_selection`
+
+```jsx
+<Element
+  backgroundColor="color-blue-500"
+  _hover={{ backgroundColor: "color-blue-600" }}
+  _disabled={{ opacity: 0.5 }}
+  _focus={{ outline: "2px solid color-blue-400" }}
+/>
+```
+
+### Media Queries
+Define responsive styles with the `media` prop for different breakpoints:
+```jsx
+<View
+  padding={8}
+  media={{
+    tablet: { padding: 16 },
+    desktop: { padding: 24 }
+  }}
+/>
+```
 
-Use `ThemeProvider` to define global theme settings, including light/dark mode colors and custom theme tokens (e.g., `primary`, `secondary`). The `useTheme` hook provides access to the current theme mode (`themeMode`), theme configuration (`theme`), a function to switch modes (`setThemeMode`), and the essential `getColor` function to resolve color strings (like `color-blue.500` or `theme.primary`) into actual CSS color values for the current mode.
+## Theming & Colors
 
-You can also directly access specific theme mode colors using the `light-` or `dark-` prefix (e.g., `light-white` or `dark-red.200`), which will always use that specific theme mode's color regardless of the current theme setting.
+Use `ThemeProvider` to define global theme settings, including light/dark mode colors and custom theme tokens (e.g., `primary`, `secondary`). The `useTheme` hook provides access to the current theme mode (`themeMode`), theme configuration (`theme`), a function to switch modes (`setThemeMode`), and the essential `getColor` function to resolve color strings (like `color-blue-500` or `theme-primary`) into actual CSS color values for the current mode.
+
+**Color System Features:**
+- **Color Palettes**: 34 palettes with 9 shades each (50, 100, 200...900) - e.g., `color-blue-500`
+- **Singleton Colors**: 30 named colors like `color-white`, `color-gold`, `color-turquoise`
+- **Theme Colors**: Custom theme tokens like `theme-primary`, `theme-secondary`
+- **Alpha Transparency**: Add opacity to any color - `color-blue-500-200` (20% opacity) 
+- **Mode-Specific**: Direct access via `light-white` or `dark-blue-500` (ignores current theme mode)
+
+You can also directly access specific theme mode colors using the `light-` or `dark-` prefix (e.g., `light-white` or `dark-red-200`), which will always use that specific theme mode's color regardless of the current theme setting.
+
+### Color System Hierarchy
+
+```
+color-*           → Direct color access (current theme mode)
+  ├─ color-white  → Singleton colors
+  ├─ color-blue-500 → Palette colors with shades
+  └─ color-blue-500-200 → Palette colors with alpha (20% opacity)
+
+theme-*           → Custom theme configuration
+  ├─ theme-primary → Theme color
+  ├─ theme-primary-100 → Theme color with alpha (10% opacity)
+  └─ theme-button-background → Nested theme path
+
+light-*           → Always use light mode colors
+  ├─ light-white
+  └─ light-blue-500
+
+dark-*            → Always use dark mode colors
+  ├─ dark-white
+  └─ dark-red-200
+```
 
 ## Responsiveness
 
@@ -152,7 +213,7 @@ function MyStyledElement() {
 }
 ```
 
-In addition to global theming via `ThemeProvider`, the `Element` component offers granular control through the `themeMode`, `colors`, and `theme` props. When specified, these props locally override the context provided by `ThemeProvider` for this specific element instance and how its style props (like `backgroundColor="theme.primary"` or `color="color-blue-500"`) resolve color values. `themeMode` forces 'light' or 'dark' mode resolution, `colors` provides a custom `{ main, palette }` object, and `theme` supplies custom token mappings (e.g., `{ primary: 'color-purple-500' }`). This allows creating distinctly styled sections or components without altering the global theme, useful for sidebars, specific UI states, or component variations.
+In addition to global theming via `ThemeProvider`, the `Element` component offers granular control through the `themeMode`, `colors`, and `theme` props. When specified, these props locally override the context provided by `ThemeProvider` for this specific element instance and how its style props (like `backgroundColor="theme-primary"` or `color="color-blue-500"`) resolve color values. `themeMode` forces 'light' or 'dark' mode resolution, `colors` provides a custom `{ main, palette }` object, and `theme` supplies custom token mappings (e.g., `{ primary: 'color-purple-500' }`). This allows creating distinctly styled sections or components without altering the global theme, useful for sidebars, specific UI states, or component variations.
 
 **Example (Local Theme Override):**
 
@@ -179,7 +240,7 @@ function LocallyThemedSection() {
       theme={localThemeOverride}
       colors={localDarkColorsOverride}
       // Styles below will resolve using the LOCAL dark theme override defined above:
-      backgroundColor="theme.secondary" // Resolves to 'color-teal-300' via localThemeOverride in dark mode
+      backgroundColor="theme-secondary" // Resolves to 'color-teal-300' via localThemeOverride in dark mode
       borderRadius={8}
     >
       <Text color="color-white"
@@ -187,7 +248,7 @@ function LocallyThemedSection() {
         This section forces dark mode with an orange primary, even if the app is light-
       </Text>
       <Element marginTop={8} padding={10} backgroundColor="color-gray-700"> {/* Uses local dark palette */}
-         <Text color="theme.primary">Nested Primary (Orange)</Text> {/* Still uses local override */}
+         <Text color="theme-primary">Nested Primary (Orange)</Text> {/* Still uses local override */}
       </Element>
     </Element>
   );
@@ -259,7 +320,7 @@ function MyText() {
     <Text
       fontSize="xl"
       fontWeight="bold"
-      color="theme.primary"
+      color="theme-primary"
       textAlign="center"
       toUpperCase
     >
@@ -619,7 +680,7 @@ Manages the application's theme, including color palettes, light/dark modes, and
 
 **Context Values (via `useTheme`)**
 
-*   `getColor(colorName, mode?)`: Resolves a color string (e.g., `color-blue.500`, `theme.primary`, `blackAlpha.500`) to its CSS value for the specified or current theme mode.
+*   `getColor(colorName, mode?)`: Resolves a color string (e.g., `color-blue-500`, `theme-primary`, `blackAlpha-500`) to its CSS value for the specified or current theme mode.
 *   `theme`: The merged theme configuration object.
 *   `themeMode`: The current mode ('light' or 'dark').
 *   `setThemeMode(mode)`: Function to change the theme mode.
@@ -789,7 +850,8 @@ Explore our comprehensive documentation to learn more about App-Studio:
 - [Getting Started](docs/README.md) - Quick start guide and core concepts
 - [Components](docs/Components.md) - Detailed documentation of all available components
 - [Hooks](docs/Hooks.md) - Guide to the React hooks provided by App-Studio
-- [Theming](docs/Theming.md) - How to customize the look and feel of your app
+- [Theming](docs/Theming.md) - Color systems, theme colors, palettes, and light/dark modes
+- [Styling](docs/Styling.md) - Advanced guide to state modifiers, pseudo-elements, media queries, and CSS system
 - [Animation](docs/Animation.md) - Creating animations with App-Studio
 - [Responsive Design](docs/Responsive.md) - Building responsive layouts
 - [Design System](docs/Design.md) - Understanding the design system