docs: improve docs, fix mistakes

cray0000 · cray0000 · commit ae4262352bcd · 2026-01-26T17:15:36.000+02:00
diff --git a/docs/api/css.md b/docs/api/css.md
@@ -116,11 +116,11 @@ The custom `u` unit works in `css` too:
 ### Part Selectors
 
 ```css
-.button::part(icon) {
+.button:part(icon) {
   color: red;
 }
 
-.button::part(text) {
+.button:part(text) {
   font-weight: bold;
 }
 ```
diff --git a/docs/api/jsx-props.md b/docs/api/jsx-props.md
@@ -82,7 +82,7 @@ function ProgressBar({ progress }) {
 
 ## part
 
-Expose an element for external styling via `::part()`.
+Expose an element for external styling via `:part()`.
 
 ```jsx
 function Button({ children }) {
@@ -101,17 +101,17 @@ Parent components can then style these parts:
 
 ```jsx
 styl`
-  .my-button::part(icon)
+  .my-button:part(icon)
     color gold
-  .my-button::part(text)
+  .my-button:part(text)
     font-weight bold
 `
 ```
 
 ### How Parts Work
 
 1. Child component marks elements with `part="name"`
-2. Parent uses `::part(name)` selector to target those elements
+2. Parent uses `:part(name)` selector to target those elements
 3. Babel transforms both sides to connect them automatically
 
 See the [Component Parts guide](/guide/component-parts) for detailed examples.
diff --git a/docs/api/styl-function.md b/docs/api/styl-function.md
@@ -95,15 +95,15 @@ function Parent() {
   styl`
     .card
       background white
-    .card::part(title)
+    .card:part(title)
       font-weight bold
-    .card::part(icon)
+    .card:part(icon)
       color blue
   `
 }
 ```
 
-The part styles from both class selectors (`.card::part(title)`) and inline (`titleStyle`) are merged together.
+The part styles from both class selectors (`.card:part(title)`) and inline (`titleStyle`) are merged together.
 
 ## Combining with Props
 
diff --git a/docs/api/styl.md b/docs/api/styl.md
@@ -197,7 +197,7 @@ See [CSS Variables](/api/variables) for runtime variable updates.
 | `.class` | Class selector |
 | `.class1.class2` | Multiple classes (same element) |
 | `&.modifier` | Modifier class (used within parent) |
-| `::part(name)` | Part selector |
+| `:part(name)` | Part selector |
 
 > **Note:** Descendant selectors (`.parent .child`) are not supported. Apply modifiers directly to each element that needs styling.
 
@@ -208,10 +208,10 @@ See [CSS Variables](/api/variables) for runtime variable updates.
 Target internal parts of child components:
 
 ```stylus
-.button::part(icon)
+.button:part(icon)
   color red
 
-.button::part(text)
+.button:part(text)
   font-weight bold
 ```
 
diff --git a/docs/examples/card.md b/docs/examples/card.md
@@ -63,7 +63,7 @@ function Card({ title, subtitle, children, actions }) {
 
 ## Styling from Parent
 
-Use `::part()` selectors to customize the card from parent components:
+Use `:part()` selectors to customize the card from parent components:
 
 ```jsx
 import { styl } from 'cssxjs'
@@ -92,14 +92,14 @@ function ProductCard({ product }) {
     .product-card
       max-width 320px
 
-      &::part(header)
-        background linear-gradient(135deg, #667eea, #764ba2)
+      &:part(header)
+        background #667eea
         padding 16px 20px
 
-      &::part(title)
+      &:part(title)
         color white
 
-      &::part(subtitle)
+      &:part(subtitle)
         color rgba(255,255,255,0.8)
         font-size 20px
         font-weight 600
@@ -121,5 +121,5 @@ function ProductCard({ product }) {
 ## Key Concepts
 
 - **`part` attribute** exposes elements for external styling
-- **`::part()` selector** targets parts from parent components
+- **`:part()` selector** targets parts from parent components
 - **Encapsulation** — Card defines structure, parent customizes appearance
diff --git a/docs/guide/component-parts.md b/docs/guide/component-parts.md
@@ -22,9 +22,9 @@ How can a parent component customize the icon or text styles? With traditional a
 - Use complex class name conventions
 - Expose internal implementation details
 
-## The Solution: `part` and `::part()`
+## The Solution: `part` and `:part()`
 
-CSSX solves this with the `part` attribute and `::part()` selector:
+CSSX solves this with the `part` attribute and `:part()` selector:
 
 ### Step 1: Expose Parts in the Component
 
@@ -57,7 +57,7 @@ function Button({ icon, children }) {
 
 ### Step 2: Style Parts from the Parent
 
-Use `::part()` (or `:part()`) to target those parts:
+Use `:part()` (or `:part()`) to target those parts:
 
 ```jsx
 function App() {
@@ -72,9 +72,9 @@ function App() {
   styl`
     .primary-button
       background #28a745
-    .primary-button::part(icon)
+    .primary-button:part(icon)
       color gold
-    .primary-button::part(text)
+    .primary-button:part(text)
       font-weight bold
       text-transform uppercase
   `
@@ -85,7 +85,7 @@ The parent's styles are merged with the component's internal styles.
 
 ## How It Works
 
-When you use `::part(name)`, CSSX:
+When you use `:part(name)`, CSSX:
 
 1. Creates a style prop named `{name}Style` (e.g., `iconStyle`, `textStyle`)
 2. Passes it automatically to the child component
@@ -95,7 +95,7 @@ When you use `::part(name)`, CSSX:
 // This:
 <Button styleName="my-button" />
 styl`
-  .my-button::part(icon)
+  .my-button:part(icon)
     color red
 `
 
@@ -119,7 +119,7 @@ styl`
 <Button style={{ background: 'green' }} />
 ```
 
-You don't need to write `::part(root)` explicitly — just style the class directly. This makes `part="root"` work seamlessly with any component that accepts a `style` prop, including third-party components and React Native built-ins.
+You don't need to write `:part(root)` explicitly — just style the class directly. This makes `part="root"` work seamlessly with any component that accepts a `style` prop, including third-party components and React Native built-ins.
 
 ## Complete Example
 
@@ -189,13 +189,12 @@ function App() {
 
     .featured-card
       flex 1
-      &::part(root)
-        background linear-gradient(135deg, #667eea, #764ba2)
-      &::part(header)
+      background #667eea
+      &:part(header)
         border-bottom-color rgba(255,255,255,0.2)
-      &::part(title)
+      &:part(title)
         color white
-      &::part(content)
+      &:part(content)
         color rgba(255,255,255,0.9)
   `
 }
@@ -216,10 +215,10 @@ function Page() {
   )
 
   styl`
-    .page::part(sidebar)
+    .page:part(sidebar)
       width 250px
 
-    .main-card::part(header)
+    .main-card:part(header)
       background #f5f5f5
   `
 }
@@ -252,13 +251,13 @@ Combine class selectors with parts for conditional styling:
 
 ```jsx
 styl`
-  .button::part(icon)
+  .button:part(icon)
     color gray
 
-  .button.primary::part(icon)
+  .button.primary:part(icon)
     color white
 
-  .button.danger::part(icon)
+  .button.danger:part(icon)
     color red
 `
 ```
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -35,7 +35,7 @@ import { styl } from 'cssxjs'
 
 function Button({ children }) {
   return (
-    <div part="root" styleName="root">
+    <div styleName="root">
       {children}
     </div>
   )
@@ -49,16 +49,14 @@ function Button({ children }) {
 }
 ```
 
-The `part="root"` attribute allows parent components to style this element using `::part(root)` — a powerful composition pattern.
-
 You can also use plain CSS if you prefer:
 
 ```jsx
 import { css } from 'cssxjs'
 
 function Button({ children }) {
   return (
-    <div part="root" styleName="root">
+    <div styleName="root">
       {children}
     </div>
   )
@@ -97,12 +95,14 @@ Works seamlessly on both **React Native** and **Web** (via react-native-web):
 Style internal parts of child components from the parent — similar to CSS Shadow Parts:
 
 ```jsx
-// Parent can style Button's internal parts
+// Parent can style Button and its internal parts
 styl`
-  .myButton::part(icon)
-    color green
-  .myButton::part(text)
-    font-weight bold
+  .myButton
+    background green
+    &:part(icon)
+      color gold
+    &:part(text)
+      font-weight bold
 `
 ```
 
@@ -138,14 +138,17 @@ Automatic style caching prevents unnecessary re-renders. With the optional teamp
 2. **Runtime**: The `styleName` prop applies matching styles based on class names
 3. **Parts**: Components expose styled parts that parents can override
 
+Use the `part` attribute to mark elements that can be styled from outside. The special `part="root"` maps to the standard `style` prop, letting parent components style your component directly:
+
 ```jsx
+// Card.jsx
 import { styl } from 'cssxjs'
 
-function Card({ children, variant }) {
+function Card({ title, children }) {
   return (
-    <div part="root" styleName={['root', variant]}>
+    <div part="root" styleName="root">
       <div part="header" styleName="header">
-        <span part="title" styleName="title">Title</span>
+        <span part="title" styleName="title">{title}</span>
       </div>
       <div part="content" styleName="content">{children}</div>
     </div>
@@ -156,9 +159,6 @@ function Card({ children, variant }) {
       background white
       border-radius 8px
 
-      &.primary
-        border 2px solid var(--primary-color)
-
     .header
       padding 2u
 
@@ -172,6 +172,29 @@ function Card({ children, variant }) {
 }
 ```
 
+```jsx
+// App.jsx — styling Card from the parent
+import { styl } from 'cssxjs'
+import { Card } from './Card'
+
+function App() {
+  return (
+    <Card styleName="featured-card" title="Welcome">
+      Hello world!
+    </Card>
+  )
+
+  styl`
+    .featured-card
+      background #667eea
+      &:part(title)
+        color white
+      &:part(content)
+        color rgba(255,255,255,0.9)
+  `
+}
+```
+
 ## Next Steps
 
 - [Installation](/guide/installation) - Set up CSSX in your project
diff --git a/docs/guide/pug.md b/docs/guide/pug.md
@@ -212,7 +212,7 @@ function UserProfile({ user, isOnline, onLogout }) {
       align-items center
       gap 16px
       padding 20px
-      background linear-gradient(135deg, #667eea, #764ba2)
+      background #667eea
 
     .avatar
       width 64px
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
@@ -226,7 +226,7 @@ CSSX runs on React Native, so not all CSS features are available.
 | Class selectors | `.card`, `.button` | |
 | Compound selectors | `.card.featured` | Same element |
 | Parent reference `&` | `&.active`, `&.disabled` | `styl` only |
-| Part selectors | `::part(icon)`, `:part(text)` | |
+| Part selectors | `:part(icon)`, `:part(text)` | |
 | CSS variables | `var(--color)`, `var(--size, 16px)` | |
 | Animations | `animation fadeIn 0.3s ease` | Reanimated v4 components only |
 | Keyframes | `@keyframes fadeIn` | Reanimated v4 components only |
@@ -248,6 +248,7 @@ CSSX runs on React Native, so not all CSS features are available.
 | Descendant selectors | `.parent .child` — add modifier to child directly |
 | Attribute selectors | `[type="text"]` — use class modifiers instead |
 | `:first-child`, `:nth-child` | Handle in JS when rendering |
+| `linear-gradient`, `radial-gradient` | Use solid colors or images |
 
 ### Example: Replacing :hover
 
diff --git a/docs/index.md b/docs/index.md
@@ -21,7 +21,7 @@ features:
     details: Same styles work on iOS, Android, and Web via react-native-web. Write once, run everywhere
     icon: 📱
   - title: Component Parts
-    details: Style internal elements of child components using ::part() selectors, similar to CSS Shadow Parts
+    details: Style internal elements of child components using :part() selectors, similar to CSS Shadow Parts
     icon: 🧩
   - title: Dynamic CSS Variables
     details: Use var(--name) with runtime updates. Change themes instantly and components re-render automatically

Original file line number	Diff line number	Diff line change
@@ -116,11 +116,11 @@ The custom `u` unit works in `css` too:
`116`	`116`	`### Part Selectors`
`117`	`117`
`118`	`118`	```css
`119`		`-.button::part(icon) {`
	`119`	`+.button:part(icon) {`
`120`	`120`	`color: red;`
`121`	`121`	`}`
`122`	`122`
`123`		`-.button::part(text) {`
	`123`	`+.button:part(text) {`
`124`	`124`	`font-weight: bold;`
`125`	`125`	`}`
`126`	`126`	```