@kennethsolomon/shipkit 3.14.0 → 3.15.1

package/skills/sk:website/references/art-direction.md

@@ -0,0 +1,210 @@
+# Art Direction Reference
+
+Use this when building or reviewing the visual system for a website. Translate the business brief into a deliberate visual direction that can be implemented in code without drifting into generic AI-generated styling.
+
+## Workflow
+
+1. Pick one dominant aesthetic direction from the list below.
+2. Define 2–4 signature design moves.
+3. Choose a type strategy, palette behavior, spacing rhythm, and motion stance.
+4. Verify the style still supports clarity, trust, and conversion.
+
+---
+
+## Aesthetic Directions
+
+Choose exactly one dominant direction. Do not mix multiple directions without a clear hierarchy.
+
+### Restrained Editorial
+
+Good for: architecture studios, fashion-adjacent brands, premium consultants, galleries, publishing.
+
+Signals:
+- Strong typographic contrast (large serif headline, small sans body)
+- Generous whitespace — sections breathe
+- Sparse palette (warm white + dark neutral + one muted accent)
+- Image restraint — one strong image per section, not a grid
+
+Avoid:
+- Decorative layers that break the calm
+- Loud CTA styling that contradicts the quiet tone
+
+### Premium Product-Led
+
+Good for: SaaS, devices, premium consumer products, DTC hero pages.
+
+Signals:
+- Crisp hierarchy with product at the center
+- Focused product framing (screenshot, mockup, or isolated product shot)
+- Clear product storytelling — one benefit per section
+- Controlled accent color on a near-white or dark background
+
+Avoid:
+- Fake dashboards with no real product
+- Overstuffed hero sections with too many messages
+
+### Bold Brand-Forward
+
+Good for: agencies, challenger brands, culture-led products, streetwear, creative studios.
+
+Signals:
+- Strong contrast between sections
+- Daring type scale — headline that dominates the viewport
+- Sharper section transitions (hard cuts, not gentle fades)
+- High visual recall through one repeating graphic pattern or color block
+
+Avoid:
+- Sacrificing legibility for attitude
+- Using bold direction for trust-sensitive businesses (law, medical, finance)
+
+### Warm Hospitality
+
+Good for: cafes, boutique hotels, restaurants, lifestyle spaces, florists, bakeries.
+
+Signals:
+- Tactile, atmosphere-first imagery (real textures, warm light, food close-ups)
+- Warm neutrals — cream, sand, olive, terracotta, warm grey
+- Editorial pacing — section rhythm like a magazine spread
+- Practical info (hours, address, reservation CTA) stays visible and easy to find
+
+Avoid:
+- Corporate UI chrome that breaks the atmosphere
+- Hiding menu, hours, location, or booking link behind design
+- Stock cafe imagery when real photography is the point
+
+### Sharp Technical
+
+Good for: developer tools, B2B platforms, infrastructure products, data products, security tools.
+
+Signals:
+- Precise grid with tight alignment
+- Low visual noise — very few decorative elements
+- Strong information hierarchy — function drives layout
+- Restrained motion — only when it explains something
+
+Avoid:
+- Playful or warm treatments that undermine technical credibility
+- Dense copy with no visual breathing room
+
+### Playful Contemporary
+
+Good for: consumer apps, EdTech, food delivery, kids products, lifestyle brands targeting under-35.
+
+Signals:
+- Rounded forms, approachable typography
+- Brighter palette with confident accent colors
+- Motion used generously but purposefully
+- Illustration or character work where appropriate
+
+Avoid:
+- Looking cheap or juvenile for a premium audience
+- Overanimation that obscures the product
+
+### Quiet Luxury
+
+Good for: premium services, interior design, high-end hospitality, luxury retail, wellness brands.
+
+Signals:
+- Restraint above all — nothing superfluous
+- Tactile material cues (fabric textures, paper grain, stone)
+- Elegant typography contrast (fine serif + sparse uppercase tracking)
+- Limited palette — usually 2–3 colors maximum
+
+Avoid:
+- Gimmicky animation that breaks the calm
+- Shiny, trend-driven effects (glass, neon, gradients)
+- Too much copy — quiet luxury lets the brand speak with less
+
+---
+
+## Signature Design Moves
+
+Every strong site has 2–4 memorable moves. Choose moves that fit the direction and stick with them.
+
+Examples:
+- Oversized serif headline with tight sans-serif body underneath
+- Muted palette with one decisive high-contrast accent color
+- Image-first storytelling with minimal interface chrome around it
+- Rigid grid with one intentionally broken element per section
+- Soft material textures behind simple white interface frames
+- Full-bleed photography sections alternating with dense-type sections
+- Sticky navigation that changes color on scroll
+
+**Rule:** Two strong moves beat six weak ones. Restraint is a design decision.
+
+---
+
+## Typography Mood
+
+Choose typography to express the brand's confidence level and audience — not just to look fashionable.
+
+| Mood | Type strategy |
+|---|---|
+| Elegant and assured | Serif headline + restrained supporting sans (e.g., Playfair Display + Inter) |
+| Modern and precise | Neo-grotesk or geometric sans with strong scale control (e.g., DM Sans, Plus Jakarta Sans) |
+| Warm and neighborhood-focused | Soft serif or humanist sans pairings (e.g., Lora + Nunito, Fraunces + Manrope) |
+| Technical and credible | Clean sans with tight hierarchy, minimal ornament (e.g., IBM Plex Sans, Space Grotesk) |
+| Bold brand-forward | Display face with strong personality (e.g., Syne, Cabinet Grotesk, Clash Display) |
+| Quiet luxury | Fine-weight serif or high-tracking uppercase (e.g., Cormorant Garamond, Libre Baskerville) |
+
+**Rules:**
+- Use contrast in scale, weight, and rhythm to create hierarchy before adding more colors.
+- Never use system fonts (Arial, Helvetica, Times) — always pick with intention.
+- Two fonts maximum. One display + one body. A third only if very controlled.
+
+---
+
+## Color Behavior
+
+- One strong accent is often enough. Neutrals do most of the structural work.
+- Color guides attention — it should not paint every surface.
+- Strong contrast can come from spacing and scale, not just saturated color.
+- Trust-sensitive businesses (legal, medical, finance) need calm palettes even when layout is bold.
+- If photography is strong, reduce color complexity — let the images carry the warmth.
+
+**Custom palette rules:**
+- Never use raw Tailwind palette colors (blue-500, gray-200, etc.) — always define custom values.
+- Name colors semantically: `brand`, `accent`, `surface`, `text`, `muted`.
+- Define in `tailwind.config.js` under `theme.extend.colors`.
+
+---
+
+## Motion Stance
+
+| Level | When to use | What to use |
+|---|---|---|
+| None | Trust-sensitive, performance-critical | No animation |
+| Subtle | Most business sites | Fade + translate on scroll reveal, 200–300ms |
+| Moderate | Consumer brands, hospitality | Stagger reveals, gentle parallax, hover transitions |
+| Expressive | Agencies, entertainment, playful brands | Page transitions, character animation, scroll-driven |
+
+**Rules:**
+- Motion should support pacing, reveal hierarchy, or reinforce affordances — not decorate.
+- `transform` and `opacity` only — never animate layout properties (width, height, margin).
+- Respect `prefers-reduced-motion` — wrap all animations in the media query.
+- If the page relies on performance or trust, reduce animation density.
+
+---
+
+## Anti-Patterns
+
+Avoid in all cases:
+- Random mix of brutalism, glassmorphism, and luxury minimalism in the same page
+- Default AI startup gradients (purple → blue, dark mode glow) unless clearly warranted
+- Decorative visuals that weaken the CTA or bury practical information
+- Style direction that contradicts the business category (bold agency aesthetic for a law firm)
+- Fake UI, fake charts, fake product screenshots, fake reviews
+- Overanimated entrance sequences that delay time to content
+
+By direction:
+- **SaaS**: fake dashboards, purple glow overload, feature-card sprawl with no story
+- **Agency**: dramatic visuals with vague copy, no real proof of work
+- **Local business**: beautiful design but phone, hours, and service area are buried
+- **Hospitality**: atmospheric imagery but no menu, reservation link, or location
+
+**Recovery moves when it feels generic:**
+1. Remove one full visual layer
+2. Choose one dominant type contrast and commit to it
+3. Reduce palette to neutrals + one accent
+4. Simplify motion to a single reveal family
+5. Move practical business information higher on the page

package/skills/sk:website/references/brief-template.md

@@ -0,0 +1,121 @@
+# Website Brief Template
+
+Use this when prompting `/sk:website`. Fill in what you have — the skill will infer the rest.
+
+The fastest way to start: paste a Google Maps URL or existing website URL. The skill extracts everything automatically.
+
+---
+
+## Minimal brief (enough to start)
+
+```
+/sk:website
+
+[Business name] — [type of business] in [city/location].
+Goal: [what the site should achieve — bookings, inquiries, orders, etc.]
+CTA: [primary action — "Book a Table", "Get a Quote", "Contact Us"]
+```
+
+**Example:**
+```
+/sk:website
+
+Corner Brew — specialty coffee shop in BGC, Taguig.
+Goal: drive foot traffic and reservation inquiries.
+CTA: Reserve a Spot
+```
+
+---
+
+## Full brief (more control)
+
+```
+/sk:website
+
+**Business:** [name]
+**Type:** [cafe / law firm / freelance designer / etc.]
+**Location:** [city, region — required for local SEO]
+**Goal:** [what success looks like for this site]
+**Audience:** [who visits this business / who buys]
+**Primary CTA:** [the one action you want visitors to take]
+
+**Pages needed:**
+- Home
+- About
+- [Services / Menu / Work]
+- Contact
+- [FAQ / Gallery / Blog — optional]
+
+**Tone:** [warm and neighborhood / premium and editorial / bold and modern / etc.]
+**Primary keyword:** [what people search to find this business]
+
+**Real info to include:**
+- Address: [full address if applicable]
+- Phone: [for WhatsApp CTA — format: +63XXXXXXXXXX]
+- Hours: [e.g., Mon–Fri 7am–6pm, Sat–Sun 8am–5pm]
+- Services: [list what the business actually offers]
+- Trust signals: [certifications, years open, anything real]
+
+**Visual direction (optional):**
+- Brand adjectives: [e.g., cozy, artisan, warm, minimal]
+- Colors to use or avoid:
+- Inspiration: [URL] for [what to borrow from it]
+
+**Avoid:**
+- [patterns or styles you don't want]
+```
+
+---
+
+## URL-first brief (fastest)
+
+Just paste a URL — the skill fetches and extracts everything:
+
+```
+/sk:website
+
+[Google Maps URL or existing website URL]
+
+Goal: [what to improve or achieve]
+CTA: [primary action]
+```
+
+**Example:**
+```
+/sk:website
+
+https://maps.google.com/?q=Corner+Brew+BGC
+
+Goal: replace the outdated site with something modern and bookable.
+CTA: Reserve a Table
+```
+
+---
+
+## Revision brief
+
+Use `/sk:website --revise` when you have an existing build and client feedback:
+
+```
+/sk:website --revise
+
+Changes from the client:
+1. [Change 1 — e.g., "make the hero image warmer and more inviting"]
+2. [Change 2 — e.g., "add a gallery section on the Home page"]
+3. [Change 3 — e.g., "change the CTA from 'Contact Us' to 'Book a Table'"]
+```
+
+---
+
+## Business type examples
+
+| Business | CTA | Key pages | Niche guide |
+|---|---|---|---|
+| Specialty cafe | Visit Us / Reserve a Spot | Home, Menu, About, Find Us | cafe |
+| Restaurant | Book a Table / Order Online | Home, Menu, About, Reservations | restaurant |
+| Law firm | Schedule a Consultation | Home, Practice Areas, About, Contact | law-firm |
+| Dentist | Book an Appointment | Home, Services, About Us, Contact | dentist |
+| Yoga studio | Try a Free Class | Home, Classes, About, Schedule, Contact | gym |
+| Accountant | Get a Free Consultation | Home, Services, About, Contact, FAQ | accountant |
+| Freelance designer | View My Work / Hire Me | Home, Work, About, Contact | portfolio |
+| Real estate agent | Search Listings / Get a Valuation | Home, Listings, About, Contact | real-estate |

package/skills/sk:website/references/content-seo.md

@@ -0,0 +1,143 @@
+# Content & SEO Reference
+
+Use when writing copy, metadata, or reviewing content for a website. Helps the site communicate clearly to humans and search engines without sounding generic, manipulative, or keyword-stuffed.
+
+---
+
+## Messaging Rules
+
+- Start from the business, audience, and page goal — not from a template.
+- Lead with concrete value, not vague brand language.
+- Prefer simple claims the business can credibly support.
+- Keep headings short and scannable — under 10 words where possible.
+- Use CTAs that match the actual conversion step (not "Learn More" when you mean "Book a Table").
+- Avoid filler: "innovative solutions", "next-level", "cutting-edge", "world-class", "passionate about".
+
+**Good headline pattern:** [Who you help] + [specific outcome] + [where/context]
+- "Hand-pulled espresso and house-made pastries in the heart of BGC"
+- "Tax prep for freelancers and small businesses in Metro Manila"
+- "Criminal defense attorneys serving Houston and surrounding counties"
+
+**Bad headline pattern:** vague + buzzword + generic
+- "Crafting memorable coffee experiences" — says nothing
+- "Your trusted partner in financial success" — could be anyone
+- "Excellence in legal representation" — no specifics
+
+---
+
+## SEO Rules
+
+- Match the title tag and meta description to the page's actual search intent.
+- One primary keyword or search theme per page is usually enough.
+- Support the primary intent with natural secondary terms in headings, body copy, alt text, and internal links.
+- Do not force exact-match keyword repetition — write for humans, let intent match naturally.
+- Keep important marketing content in HTML (not JS-only rendered) for crawlability.
+
+**Title tag formula:** [Primary keyword] | [Brand name]
+- "Coffee Shop in BGC Taguig | Corner Brew"
+- "Small Business Tax Accountant Austin TX | Davis & Co."
+
+**Meta description formula:** [Audience problem or intent] + [service/offer] + [location/differentiator] + [CTA]
+- "Looking for great coffee near BGC? Corner Brew serves specialty espresso, fresh pastries, and free WiFi on 26th Street. Visit us today."
+- 150–160 characters. Every page gets a unique one.
+
+---
+
+## Local SEO
+
+Use when the business serves a geographic area — cafes, restaurants, law firms, clinics, contractors, etc.
+
+**Always confirm these inputs:**
+- Primary service and secondary services
+- City, metro area, or specific neighborhood
+- Secondary service areas (if any)
+- Contact phone number
+- Street address (if physical location)
+- Business hours
+- Appointment/booking CTA
+
+**Content placement:**
+- Mention service + city in the hero headline naturally — not as a keyword dump
+- Add a short service-area statement in the footer or about section ("Serving Quezon City and nearby areas")
+- Include trust sections that fit: process, years in business, certifications, FAQs — only if real
+- Use FAQ sections for genuine customer objections, not SEO filler
+
+**Local metadata checklist:**
+- Title tag: [Service] in [City] | [Brand] (e.g., "Cafe in Tomas Morato | Kape Republic")
+- Meta description: mentions the audience, service, and location in plain language
+- H1: reflects the page's local search intent
+- Footer: include full address, phone, and hours where applicable
+- Structured data: `LocalBusiness` (or a more specific subtype)
+
+**Structured data — LocalBusiness:**
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "[BusinessType]",
+  "name": "[Business Name]",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "[Street]",
+    "addressLocality": "[City]",
+    "addressRegion": "[Region]",
+    "addressCountry": "[Country Code]"
+  },
+  "telephone": "[Phone]",
+  "openingHours": ["Mo-Fr 08:00-18:00", "Sa 09:00-17:00"],
+  "url": "[Site URL]"
+}
+```
+
+Use `CafeOrCoffeeShop` for cafes, `Restaurant` for restaurants, `LegalService` for law firms, `Dentist` for dental, `MedicalBusiness` for clinics, `LocalBusiness` as fallback.
+
+**Avoid:**
+- Thin city pages with near-duplicate copy
+- Fake office locations
+- Invented reviews or star ratings
+- Keyword repetition that makes copy sound mechanical
+- Separate "city pages" unless each one is genuinely different
+
+---
+
+## Page-Level SEO Checklist
+
+For every page generated, verify:
+
+- [ ] Unique `<title>` tag (not duplicated from another page)
+- [ ] Unique meta description (150–160 characters)
+- [ ] One H1 that matches the page's primary intent
+- [ ] Supporting H2s and H3s that structure the content logically
+- [ ] OG `title`, `description`, and `image` defined
+- [ ] Twitter card metadata defined
+- [ ] Canonical URL set (no duplicate content)
+- [ ] Structured data where applicable
+- [ ] All important text is in HTML (not JS-rendered)
+- [ ] Internal links to related pages (e.g., Services → Contact)
+
+---
+
+## Internal Linking Strategy
+
+- Home → Services, About, Contact (primary CTAs in nav and hero)
+- Services → Contact (each service should have a CTA to book/inquire)
+- About → Services, Contact (trust-building page leads to action)
+- Blog/FAQ posts → relevant service pages (if applicable)
+- Footer: always links to all top-level pages + legal pages
+
+---
+
+## Content Anti-Patterns
+
+Never produce:
+- "Lorem ipsum" or any placeholder body copy
+- Generic `[Your Headline Here]` style template text
+- Invented testimonials, star ratings, or review counts
+- Made-up certifications, awards, or rankings
+- Fake "as seen in" media logos
+- Invented pricing or "starting from" numbers without real data
+- Claims like "best in [city]" without real proof
+
+Always prefer:
+- Specific over vague ("3 espresso origins rotating weekly" > "quality coffee")
+- Verifiable over invented ("Open since 2019" vs. "20 years of experience" when unknown)
+- Direct over clever ("Book a table" vs. "Experience our hospitality")