axiom-coding-agent-setup 1.0.10 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-custom-components-v2/references/theme-css-variables.md

@@ -0,0 +1,243 @@
+## Streamlit theme CSS variables for CCv2 components (`--st-*`)
+
+Streamlit injects a set of `--st-*` CSS custom properties into CCv2 components so your component can match the app’s active theme from within your component CSS (including when `isolate_styles=True` and you’re rendering inside a shadow root).
+
+**Recommendation:** Prefer `var(--st-…)` over hard-coded colors and sizes. These variables automatically adapt to a user's current Streamlit theme (light/dark/custom), so most components **do not** need separate “dark mode vs light mode” styling.
+
+## Contents
+
+- Quick start
+- Gotchas: serialization + fallbacks
+- Cheat sheet: the 90% variables (intent → `--st-*`)
+- Foundation tokens (surfaces, text, borders, shape)
+- Typography tokens
+- Data display tokens (dataframes/tables)
+- Data visualization tokens (chart palettes)
+- Semantic/status palette (red/green/etc.)
+- Appendix: full variable index (alphabetical)
+
+### Quick start
+
+Use them like any CSS variable:
+
+```css
+.card {
+  background: var(--st-secondary-background-color);
+  color: var(--st-text-color);
+  border: 1px solid var(--st-border-color);
+  border-radius: var(--st-base-radius);
+}
+
+.primaryButton {
+  background: var(--st-primary-color);
+  color: var(--st-background-color);
+  border-radius: var(--st-button-radius);
+}
+```
+
+### Gotchas: serialization rules + safe fallbacks
+
+These variables originate from Streamlit’s theme object and are serialized into strings:
+
+- **Strings**: passed through (e.g. `--st-primary-color: #ff4b4b`).
+- **Numbers**: stringified (e.g. `--st-base-font-weight: 400`).
+- **Booleans**: become `"1"` or `"0"` (e.g. `--st-link-underline`).
+- **Arrays**: become a comma-joined string (e.g. `--st-heading-font-sizes: 2.75rem,2.25rem,...`).
+  - If you need individual items in JS, split on `","`.
+- **Missing values (`null` / `undefined`)**: become `unset` so consumers fall back to initial/inherited CSS behavior.
+
+### Cheat sheet: the 90% variables (intent → `--st-*`)
+
+Use this section as your starting point. It covers what most components need most of the time.
+
+| Intent                    | Variables                                                              |
+| ------------------------- | ---------------------------------------------------------------------- |
+| App/page background       | `--st-background-color`                                                |
+| Panel/card background     | `--st-secondary-background-color`                                      |
+| Body text                 | `--st-text-color`                                                      |
+| Headings                  | `--st-heading-color`, `--st-heading-font`                              |
+| Primary accent / emphasis | `--st-primary-color`                                                   |
+| Links                     | `--st-link-color`, `--st-link-underline`                               |
+| Borders / dividers        | `--st-border-color`, `--st-border-color-light`                         |
+| Widget outline borders    | `--st-widget-border-color`                                             |
+| Corner radius             | `--st-base-radius`, `--st-button-radius`                               |
+| Code blocks               | `--st-code-background-color`, `--st-code-text-color`, `--st-code-font` |
+
+### Foundation tokens (surfaces, text, borders, shape)
+
+#### Surfaces and content colors
+
+- `--st-background-color` (page background)
+- `--st-secondary-background-color` (panels, cards, containers)
+- `--st-text-color` (default text)
+- `--st-heading-color` (derived heading color)
+- `--st-primary-color` (brand / accent)
+- `--st-link-color` (link color)
+- `--st-link-underline` (boolean serialized to `"1"` / `"0"`)
+
+#### Borders and separators
+
+- `--st-border-color` (default borders/dividers)
+- `--st-border-color-light` (derived lighter border)
+- `--st-widget-border-color` (widget borders)
+
+#### Shape (radii)
+
+- `--st-base-radius`
+- `--st-button-radius`
+
+#### Code block colors
+
+- `--st-code-background-color`
+- `--st-code-text-color`
+
+### Typography tokens
+
+#### Font families
+
+- `--st-font` (body font)
+- `--st-heading-font`
+- `--st-code-font`
+
+#### Body sizing and weights
+
+- `--st-base-font-size`
+- `--st-base-font-weight` (number)
+
+#### Headings (H1–H6)
+
+Arrays (comma-joined):
+
+- `--st-heading-font-sizes` (array; typically 6 values for H1–H6)
+- `--st-heading-font-weights` (array; typically 6 values for H1–H6)
+
+Per-level convenience variables:
+
+- `--st-heading-font-size-1`
+- `--st-heading-font-size-2`
+- `--st-heading-font-size-3`
+- `--st-heading-font-size-4`
+- `--st-heading-font-size-5`
+- `--st-heading-font-size-6`
+- `--st-heading-font-weight-1` (number)
+- `--st-heading-font-weight-2` (number)
+- `--st-heading-font-weight-3` (number)
+- `--st-heading-font-weight-4` (number)
+- `--st-heading-font-weight-5` (number)
+- `--st-heading-font-weight-6` (number)
+
+#### Code typography
+
+- `--st-code-font-size`
+- `--st-code-font-weight` (number)
+
+### Data display tokens (dataframes/tables)
+
+- `--st-dataframe-border-color`
+- `--st-dataframe-header-background-color`
+
+### Data visualization tokens (chart palettes)
+
+Chart palette variables are **arrays serialized as comma-joined strings**:
+
+- `--st-chart-categorical-colors` (discrete series)
+- `--st-chart-sequential-colors` (low → high)
+- `--st-chart-diverging-colors` (negative ↔ positive around a midpoint)
+
+If you need the palette values in JS, split on commas:
+
+```js
+export default function (component) {
+  const { parentElement } = component;
+
+  const host = parentElement.host ?? parentElement;
+  const raw = getComputedStyle(host)
+    .getPropertyValue('--st-chart-categorical-colors')
+    .trim();
+  const palette = raw ? raw.split(',') : [];
+}
+```
+
+### Semantic/status palette
+
+These are best for status UI (badges, alerts, validation messages), not for primary layout surfaces.
+
+Each “family” typically comes in three variants:
+
+- **Base**: `--st-<name>-color`
+- **Background**: `--st-<name>-background-color`
+- **Text**: `--st-<name>-text-color`
+
+Families:
+
+- Red: `--st-red-color`, `--st-red-background-color`, `--st-red-text-color`
+- Orange: `--st-orange-color`, `--st-orange-background-color`, `--st-orange-text-color`
+- Yellow: `--st-yellow-color`, `--st-yellow-background-color`, `--st-yellow-text-color`
+- Blue: `--st-blue-color`, `--st-blue-background-color`, `--st-blue-text-color`
+- Green: `--st-green-color`, `--st-green-background-color`, `--st-green-text-color`
+- Violet: `--st-violet-color`, `--st-violet-background-color`, `--st-violet-text-color`
+- Gray: `--st-gray-color`, `--st-gray-background-color`, `--st-gray-text-color`
+
+### Appendix: full variable index (alphabetical)
+
+- `--st-background-color`
+- `--st-base-font-size`
+- `--st-base-font-weight`
+- `--st-base-radius`
+- `--st-blue-background-color`
+- `--st-blue-color`
+- `--st-blue-text-color`
+- `--st-border-color`
+- `--st-border-color-light`
+- `--st-button-radius`
+- `--st-chart-categorical-colors`
+- `--st-chart-diverging-colors`
+- `--st-chart-sequential-colors`
+- `--st-code-background-color`
+- `--st-code-font`
+- `--st-code-font-size`
+- `--st-code-font-weight`
+- `--st-code-text-color`
+- `--st-dataframe-border-color`
+- `--st-dataframe-header-background-color`
+- `--st-font`
+- `--st-gray-background-color`
+- `--st-gray-color`
+- `--st-gray-text-color`
+- `--st-green-background-color`
+- `--st-green-color`
+- `--st-green-text-color`
+- `--st-heading-color`
+- `--st-heading-font`
+- `--st-heading-font-size-1`
+- `--st-heading-font-size-2`
+- `--st-heading-font-size-3`
+- `--st-heading-font-size-4`
+- `--st-heading-font-size-5`
+- `--st-heading-font-size-6`
+- `--st-heading-font-sizes`
+- `--st-heading-font-weight-1`
+- `--st-heading-font-weight-2`
+- `--st-heading-font-weight-3`
+- `--st-heading-font-weight-4`
+- `--st-heading-font-weight-5`
+- `--st-heading-font-weight-6`
+- `--st-heading-font-weights`
+- `--st-link-color`
+- `--st-link-underline`
+- `--st-orange-background-color`
+- `--st-orange-color`
+- `--st-orange-text-color`
+- `--st-primary-color`
+- `--st-red-background-color`
+- `--st-red-color`
+- `--st-red-text-color`
+- `--st-secondary-background-color`
+- `--st-text-color`
+- `--st-violet-background-color`
+- `--st-violet-color`
+- `--st-violet-text-color`
+- `--st-widget-border-color`
+- `--st-yellow-background-color`
+- `--st-yellow-color`
+- `--st-yellow-text-color`

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-custom-components-v2/references/troubleshooting.md

@@ -0,0 +1,121 @@
+## Troubleshooting CCv2 components
+
+## Contents
+
+- Packaged assets and manifests (`asset_dir`, component key)
+- Renaming / placeholder drift
+- Inline strings vs file-backed assets (path heuristic)
+- Globs (0 matches or multiple matches)
+- Defaults, callbacks, and missing result attributes
+- Keys (Python `key=` vs frontend `key`)
+- Shadow DOM / `isolate_styles` surprises
+- Frontend build (Vite) gotchas
+- DOM clobbering (overwriting injected HTML/CSS)
+
+### Packaged assets and manifests (`asset_dir`, component key)
+
+#### “Component '<name>' must be declared in pyproject.toml with asset_dir to use file-backed js/css.”
+
+You passed a **path-like** `js=`/`css=` string (like `index-*.js` or `assets/index-*.js`) but Streamlit can’t find an `asset_dir` for this component key.
+
+Fix:
+
+- If you want **inline JS/CSS**, pass a **multi-line** string with the actual code (not a path).
+- If you want **packaged assets**, ensure:
+  - Your wheel includes a `pyproject.toml` with `[[tool.streamlit.component.components]] ... asset_dir = ...`
+  - You call `st.components.v2.component("<project>.<component>", js="...", css="...")` with the matching fully-qualified key.
+
+Important context:
+
+- This error is expected if you test packaged wrappers via plain Python import in some environments.
+- Prefer `streamlit run ...` for packaged verification because manifest discovery is part of Streamlit runtime initialization.
+
+### Inline strings vs file-backed assets (path heuristic)
+
+CCv2 uses a heuristic: strings that “look like” paths are treated as file references. A multi-line string is always treated as inline content.
+
+Fix:
+
+- Prefer triple-quoted multi-line strings for inline `html`/`css`/`js`.
+- Avoid single-line minified JS/CSS in `js=`/`css=`; add a newline if you must.
+
+### Globs (0 matches or multiple matches)
+
+Globs must match **exactly one** file under `asset_dir`.
+
+Fix:
+
+- Clean the build output directory before rebuilding.
+- Make your bundler output a predictable `index-<hash>.js` / `index-<hash>.css` (or `assets/index-<hash>...` if you emit into an `assets/` subdir).
+- If you started from Streamlit’s `component-template`, run `npm run clean` from your `frontend/` directory to clear the `build/` output so `index-*.js` matches exactly one file.
+
+### Renamed project/package still shows old template names
+
+Symptoms:
+
+- Old names like `streamlit-component-x` / `streamlit_component_x` remain in paths or metadata.
+- Imports, manifest component keys, and registration keys no longer align.
+
+Fix:
+
+- Rename/update all related surfaces together:
+  - root `pyproject.toml` project name
+  - import package folder and `MANIFEST.in` paths
+  - `[tool.setuptools.packages.find]` and `[tool.setuptools.package-data]`
+  - in-package manifest (`<import_name>/pyproject.toml`)
+  - wrapper registration key (`"<project.name>.<component.name>"`)
+  - README/example imports and install commands
+- Rebuild frontend and reinstall editable package after rename.
+
+### Defaults, callbacks, and missing result attributes
+
+#### `default={...}` doesn’t apply / missing result attributes
+
+Defaults only apply to **state keys**, and Streamlit expects those keys to be declared via `on_<key>_change` callback parameters at mount time.
+
+Fix:
+
+- If you pass `default={"value": ...}`, also pass `on_value_change=lambda: None`.
+- For triggers, don’t expect defaults; triggers are transient and default to `None`.
+
+### Keys (Python `key=` vs frontend `key`)
+
+- Python `key=` is the user-visible Streamlit element key.
+- The frontend also receives a `key` string that is **generated by Streamlit** and is not the same as the Python `key` unless you explicitly pass the user key through `data`.
+
+Fix:
+
+- If your frontend needs a stable identifier, pass it in `data={"user_key": key, ...}`.
+
+### Shadow DOM / `isolate_styles` surprises
+
+#### Shadow DOM (`isolate_styles=True`) surprises
+
+With `isolate_styles=True` (default):
+
+- Your component is mounted in a **shadow root**.
+- `parentElement` is a `ShadowRoot`.
+- Global CSS (like Tailwind injected into the document) won’t automatically style your component.
+
+Fix:
+
+- Keep `isolate_styles=True` for safety and use CSS variables and component-local styles.
+- Use `isolate_styles=False` only when you intentionally need global styling behavior.
+
+### Frontend build gotchas (Vite)
+
+If you deviate from the template’s Vite config (or you’re wiring Vite into an existing repo), these are the common footguns:
+
+- **Missing `base: "./"`**: relative asset URLs can break when served from Streamlit’s component URL path.
+- **Stale build artifacts**: Vite outputs hashed filenames; if you keep old builds around, `index-*.js` can match multiple files. Clean the build dir before rebuilding.
+
+### DOM clobbering (overwriting injected HTML/CSS)
+
+#### Accidentally overwriting your component DOM
+
+If you directly set `parentElement.innerHTML = ...`, you can overwrite the HTML/CSS that Streamlit injected from your `html=`/`css=` arguments.
+
+Fix:
+
+- Prefer `querySelector` + modifying children.
+- If you need dynamic HTML, create a new child element and set **that** element’s `innerHTML`.

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-dashboards/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: building-streamlit-dashboards
+description: Building dashboards in Streamlit. Use when creating KPI displays, metric cards, or data-heavy layouts. Covers borders, cards, responsive layouts, and dashboard composition.
+license: Apache-2.0
+---
+
+# Streamlit dashboards
+
+Compose metrics, charts, and data into clean dashboard layouts.
+
+## Cards with borders
+
+Use `border=True` to create visual cards. Supported on `st.container`, `st.metric`, `st.columns`, and `st.form`:
+
+```python
+# Container card
+with st.container(border=True):
+    st.subheader("Sales Overview")
+    st.line_chart(sales_data)
+
+# Metric card
+st.metric("Revenue", "$1.2M", "+12%", border=True)
+
+# Column cards
+for col in st.columns(3, border=True):
+    with col:
+        st.metric("Users", "1.2k")
+```
+
+## Card labels
+
+Add context to cards with headers or bold text:
+
+```python
+# With subheader
+with st.container(border=True):
+    st.subheader("Monthly Trends")
+    st.line_chart(data)
+
+# With bold label
+with st.container(border=True):
+    st.markdown("**Top Products**")
+    st.dataframe(top_products)
+```
+
+## KPI rows
+
+Use horizontal containers for responsive metric rows:
+
+```python
+with st.container(horizontal=True):
+    st.metric("Revenue", "$1.2M", "-7%", border=True)
+    st.metric("Users", "762k", "+12%", border=True)
+    st.metric("Orders", "1.4k", "+5%", border=True)
+```
+
+Horizontal containers wrap on smaller screens. Prefer them over `st.columns` for metric rows.
+
+## Metrics with sparklines
+
+Add trend context with `chart_data`:
+
+```python
+weekly_values = [700, 720, 715, 740, 762, 755, 780]
+
+st.metric(
+    "Active Users",
+    "780k",
+    "+3.2%",
+    border=True,
+    chart_data=weekly_values,
+    chart_type="line",  # or "bar"
+)
+```
+
+Sparklines show y-values only—use for evenly-spaced data like daily/weekly snapshots.
+
+## Dashboard layout
+
+Combine cards into a dashboard:
+
+```python
+# KPI row
+with st.container(horizontal=True):
+    st.metric("Revenue", "$1.2M", "-7%", border=True, chart_data=rev_trend, chart_type="line")
+    st.metric("Users", "762k", "+12%", border=True, chart_data=user_trend, chart_type="line")
+    st.metric("Orders", "1.4k", "+5%", border=True, chart_data=order_trend, chart_type="bar")
+
+# Charts row
+col1, col2 = st.columns(2)
+with col1:
+    with st.container(border=True):
+        st.subheader("Revenue by Region")
+        st.bar_chart(region_data, x="region", y="revenue")
+
+with col2:
+    with st.container(border=True):
+        st.subheader("Monthly Trend")
+        st.line_chart(monthly_data, x="month", y="value")
+
+# Data table
+with st.container(border=True):
+    st.subheader("Recent Orders")
+    st.dataframe(orders_df, hide_index=True)
+```
+
+## Sidebar filters
+
+Put filters in the sidebar to maximize dashboard space:
+
+```python
+with st.sidebar:
+    date_range = st.date_input("Date range", value=(start, end))
+    region = st.multiselect("Region", regions, default=regions)
+    
+# Main area is all dashboard content
+```
+
+## Dashboard templates
+
+Ready-to-use dashboard templates are available in `templates/apps/`:
+
+| Template | Features |
+|----------|----------|
+| `dashboard-metrics` | Metric cards with sparklines, date filtering, focus mode |
+| `dashboard-metrics-snowflake` | Same as above, with Snowflake connection |
+| `dashboard-companies` | Company comparison, filterable data tables |
+| `dashboard-compute` | `@st.fragment` for independent updates, popover filters |
+| `dashboard-compute-snowflake` | Same as above, with Snowflake connection |
+| `dashboard-feature-usage` | Feature adoption tracking, trend analysis |
+| `dashboard-seattle-weather` | Weather data visualization |
+| `dashboard-stock-peers` | Stock peer comparison |
+| `dashboard-stock-peers-snowflake` | Same as above, with Snowflake connection |
+
+Each template uses synthetic data that can be replaced with real queries. See `templates/apps/README.md` for setup instructions.
+
+## Related skills
+
+- `using-streamlit-layouts`: Columns, containers, tabs, dialogs
+- `displaying-streamlit-data`: Charts, dataframes, column configuration
+- `optimizing-streamlit-performance`: Caching and fragments for heavy dashboards
+
+## References
+
+- [st.container](https://docs.streamlit.io/develop/api-reference/layout/st.container)
+- [st.metric](https://docs.streamlit.io/develop/api-reference/data/st.metric)
+- [st.columns](https://docs.streamlit.io/develop/api-reference/layout/st.columns)