# saffron-atlas/civic-signal

> A lightweight civic data explorer for comparing state populations with the US Census ACS.

- **Default branch:** `main`
- **Stars:** 0 · **Open issues:** 0 · **Open pull requests:** 0
- **Clone:** `https://gothab.io/saffron-atlas/civic-signal.git`

## README.md

# Civic Signal

An interactive, source-transparent atlas of U.S. population change. Select a state, switch between population, net change, and domestic or international migration, and compare annual estimates from 2020 to 2025.

## Run locally

The app is static and dependency-free. From the project directory, run:

```sh
python3 -m http.server 8000
```

Then open <http://localhost:8000>. (The app fetches local JSON assets, so opening `index.html` directly as a `file://` URL may be blocked by browser security.)

## Data and scope

- `data/population.json`: state and D.C. estimates from the U.S. Census Bureau, Population Estimates Program, Vintage 2025. The source CSV is [NST-EST2025-ALLDATA.csv](https://www2.census.gov/programs-surveys/popest/datasets/2020-2025/state/totals/NST-EST2025-ALLDATA.csv), under the [Census population estimates program](https://www.census.gov/programs-surveys/popest.html). Includes total population, net population change, domestic migration, and international migration for 2020–2025. The 2020 domestic migration values are present in the published source; later years provide a more useful basis for comparing recent migration. U.S. territories are excluded; D.C. is included in the 51 records.
- `data/states.geojson`: state boundaries from [PublicaMundi/MappingAPI](https://github.com/PublicaMundi/MappingAPI/blob/master/data/geojson/us-states.json), an open GeoJSON dataset. The original boundary file includes Puerto Rico, excluded from this state-focused visualization. Alaska and Hawaii are inset schematically; the map is for exploration, not navigation. D.C. is not visible at this scale.

Estimates are not decennial census counts. Component values reflect Census Bureau estimates; “domestic migration” is net movement between states, and “international migration” is the Census estimate of net movement to and from other countries. Neither represents total arrivals. The component breakdown derives natural change as net population change minus domestic and international migration; the Census balance may include a residual, so these components need not sum exactly to net change. This project is an exploratory civic-data view, not an official Census product.

## Implementation

Plain HTML, CSS, and JavaScript; no build step or third-party runtime dependencies. The app reads the committed JSON files and works offline after serving locally. Map shapes are projected in-browser; the visualization is intentionally lightweight. Keyboard users can tab to state shapes and press Enter or Space to select a state. Current state, comparison state, year, and metric are encoded in the URL, so a map view or state-to-state comparison can be bookmarked or shared; browser Back and Forward restore earlier selections. Refresh the committed data with `python3 scripts/build_data.py`; this fetches the latest configured Vintage 2025 Census CSV and state geometry from PublicaMundi, so network access is required. Refresh the year constants in the script and UI when a newer Census vintage is available.