Cam Proudlock
a9d0dfff4a
Flask + Vue rewrite of the classic-ASP shopdb, built as a plugin framework so sister GE Aerospace sites can adopt it. Product version 0.7.0-pre-0.8.0, plugin contract 0.11.0, 966 backend tests. Key entry points: - docs/INSTALL-WINDOWS-IIS.md - tested Windows + IIS install runbook (own-site and subpath deployment methods) - docs/PILOT-DEPLOY.md - production pilot: stand up + import + verify - docs/IMPORT-API.md - schema-agnostic legacy data import contract - scripts/site_imports/wjf/ - West Jefferson reference import loader - docs/adr/ - twelve accepted architecture decision records
121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# Frontend Development Standards
|
|
|
|
## Naming Convention (LOCKED)
|
|
|
|
The shopdb-flask naming convention lives in the root `CONTRIBUTING.md`. Read it before naming any variable, component, API param, or CSS class.
|
|
|
|
Frontend-specific reminders pulled from the convention:
|
|
|
|
- Variables holding API field values: match the API field name exactly. Do NOT convert to camelCase. (`response.machineid`, NOT `response.machineId`)
|
|
- Pure JS variables: camelCase (`currentUser`, `isLoading`)
|
|
- Vue components: PascalCase, spelled out (`AssetDetail.vue`, `MachineForm.vue`)
|
|
- CSS classes: lowercase with dashes (`asset-detail`, `machine-form`)
|
|
- API params sent to backend: match DB column names without underscores (`params.locationid = 5`, NOT `params.location_id`)
|
|
- No emojis, em-dashes, smart quotes, or Unicode arrows anywhere. Plain ASCII only.
|
|
- Banned shorthand as standalone variables: `cfg`, `ctx`, `mgr`, `req`, `res`, `env`, `util`, `helper`. Spell them out (`canvasContext`, `response`, `manager`, etc.). Suffix usage like `printers_bp` is allowed.
|
|
|
|
Pre-commit hook at `scripts/check-naming-and-style.sh` enforces these rules.
|
|
|
|
## CSS Styling Standards
|
|
|
|
### Use CSS Variables for ALL Colors
|
|
|
|
**NEVER hardcode colors in component styles.** Always use CSS variables defined in `src/assets/style.css`.
|
|
|
|
Available variables:
|
|
```css
|
|
--primary /* Primary brand color */
|
|
--primary-dark /* Darker primary for hover states */
|
|
--secondary /* Secondary/muted color */
|
|
--success /* Success states (green) */
|
|
--warning /* Warning states (orange) */
|
|
--danger /* Error/danger states (red) */
|
|
--bg /* Page background */
|
|
--bg-card /* Card/panel background */
|
|
--text /* Primary text color */
|
|
--text-light /* Secondary/muted text */
|
|
--border /* Border color */
|
|
--link /* Link color (bright blue in dark mode) */
|
|
```
|
|
|
|
**Bad:**
|
|
```css
|
|
.my-card {
|
|
background: white;
|
|
color: #1a1a1a;
|
|
}
|
|
```
|
|
|
|
**Good:**
|
|
```css
|
|
.my-card {
|
|
background: var(--bg-card);
|
|
color: var(--text);
|
|
}
|
|
```
|
|
|
|
### Detail Pages - Use Global Styles
|
|
|
|
All detail pages (MachineDetail, PCDetail, PrinterDetail, ApplicationDetail) should use the **unified global styles** from `style.css`:
|
|
|
|
- `.detail-page` - Container wrapper
|
|
- `.hero-card` - Main hero section with image and info
|
|
- `.hero-image`, `.hero-content`, `.hero-title`, `.hero-meta`, `.hero-details`
|
|
- `.section-card` - Info sections
|
|
- `.section-title` - Section headers
|
|
- `.info-list`, `.info-row`, `.info-label`, `.info-value`
|
|
- `.content-grid`, `.content-column` - Two-column layout
|
|
- `.audit-footer` - Created/modified timestamps
|
|
|
|
**Only add scoped styles for page-specific elements** (e.g., supplies grid for printers, version list for applications).
|
|
|
|
### PrinterDetail.vue is the Master Template for Detail Pages
|
|
|
|
Use `PrinterDetail.vue` as the reference for new detail pages. Follow its structure and styling patterns.
|
|
|
|
### List Pages - Use Global Styles
|
|
|
|
All list pages should use the **unified global styles** from `style.css`:
|
|
|
|
- `.page-header` - Header with title and action button
|
|
- `.filters` - Search and filter controls
|
|
- `.card` - Main content container
|
|
- `.table-container` - Scrollable table wrapper
|
|
- `table`, `th`, `td` - Table styling
|
|
- `.pagination` - Page navigation
|
|
- `.badge`, `.badge-success`, etc. - Status badges
|
|
- `.actions` - Action button column
|
|
|
|
**PrintersList.vue is the Master Template for List Pages**
|
|
|
|
Use `PrintersList.vue` as the reference for new list pages. It has NO scoped styles - everything uses global CSS.
|
|
|
|
**Only add scoped styles for page-specific elements** (e.g., icon cells for applications, stats badge for knowledge base).
|
|
|
|
### Dark Mode Support
|
|
|
|
Dark mode is automatic via `@media (prefers-color-scheme: dark)`. Using CSS variables ensures colors adapt automatically - no extra work needed per page.
|
|
|
|
## Component Organization
|
|
|
|
- **Global styles**: `src/assets/style.css`
|
|
- **Page-specific styles**: Scoped `<style scoped>` block, only for unique elements
|
|
- **Font sizes**: Use `rem` units, base is 18px for readability on 1080p
|
|
|
|
## File Structure
|
|
|
|
```
|
|
src/
|
|
assets/
|
|
style.css # Global styles, CSS variables, detail page styles
|
|
views/
|
|
machines/
|
|
MachineDetail.vue # Uses global styles only
|
|
pcs/
|
|
PCDetail.vue # Global + PC-specific (app-list, etc.)
|
|
printers/
|
|
PrinterDetail.vue # Global + printer-specific (supplies-grid)
|
|
applications/
|
|
ApplicationDetail.vue # Global + app-specific (version-list, pc-list)
|
|
```
|