docs

docs/developers/flats.md

@@ -2,4 +2,31 @@
 
 # Packaging flat files
 
-TK
+You can package flat files -- e.g., JPG and EPS assets -- for clients in the `media-assets/` directory.
+
+Assets must be structured using the same directory scheme as embed pages -- a folder for a valid locale and for a unique slug within the locale. The JPG and EPS filenames can be whatever you want them to be.
+
+```
+media-assets/
+  en/
+    chart/
+      chart.eps
+      chart.jpg
+    map/
+      my-map.eps
+      map-preview.jpg
+```
+
+If you have an embeddable page using the same locale/slug scheme as a set of flat assets, the publisher will upload the JPG and EPS file with the embeddable version of the same graphic.
+
+```
+pages/
+  embeds/
+    en/
+      chart.svelte
+media-assets/
+  en/
+    chart/
+      chart.eps
+      chart.jpg
+```

docs/developers/pages.md

@@ -1,5 +1,110 @@
 ![](https://graphics.thomsonreuters.com/style-assets/images/logos/reuters-graphics-logo/svg/graphics-logo-color-dark.svg)
 
-# Pages
+# Making pages
 
-TK
+The graphics kit improves on our previous [graphics rig](https://github.com/reuters-graphics/bluprint_graphics-rig/) by letting you build _multiple_ pages and embeds so you can build full-fledged newsapps or projects with several graphics components that make sense as individual embeds for media clients.
+
+## How to make pages
+
+Public pages and embeds are both created in the `pages` directory. All pages are Svelte components. To create a new one, you'll add a new `.svelte` file in that directory.
+
+```
+pages/
+  embeds/
+    en/
+      chart.svelte
+      page.svelte
+  index.svelte
+```
+
+### Public pages
+
+Public pages can be named whatever you like. The filename and directory structure will be used to create the page path. For example, a directory like this:
+
+```
+pages/
+  index.svelte
+  second-page.svelte
+  countries/
+    usa.svelte
+    uk.svelte
+```
+
+... would create pages like:
+
+```
+/index.html
+/second-page/index.html
+/countires/usa/index.html
+/countires/uk/index.html
+```
+
+Pages can also be named using dynamic parameters that can create multiple pages.
+
+```
+pages/
+  index.svelte
+  countries/
+    [code].svelte
+```
+
+Read more in [SvelteKit's docs](https://kit.svelte.dev/docs#routing-pages).
+
+#### SEO
+
+When you create public pages, you should always add SEO to them. Using our pre-built SEO component is the easiest way.
+
+```svelte
+<script>
+  import { SEO } from 'reuters-components';
+</script>
+
+<SEO
+  seoTitle="My SEO title"
+  seoDescription="My SEO description"
+  shareTitle="My share title"
+  shareDescription="My share description"
+  shareImgPath="images/reuters-graphics.jpg"
+  lang="en"
+/>
+```
+
+### Embeds
+
+Embeds for clients are more restricted in how they should be organized.
+
+Embeds must be added to the `pages/embeds/` directory under a folder named with a valid locale code -- e.g., `en`, `es`, `de`, etc. -- and can be no levels deeper than that.
+
+```
+pages/
+  embeds/
+    en/
+      page.svelte
+      chart.svelte
+      map.svelte
+    es/
+      page.svelte
+      map.svelte
+```
+
+Each of these will create a corresponding [edition](https://github.com/reuters-graphics/bluprint_graphics-kit/issues/1#issuecomment-811891029) in RNGS for clients:
+
+```
+media-en-page
+media-en-chart
+media-en-map
+media-es-page
+media-es-map
+```
+
+#### Pym
+
+Always be sure to include Pym.js on embeddable pages. Using our pre-built component is the easiest way.
+
+```svelte
+<script>
+  import { PymChild } from 'reuters-components';
+</script>
+
+<PymChild />
+```

docs/developers/styles.md

@@ -2,4 +2,59 @@
 
 # Styles
 
-TK
+Write styles in svelte components. Read more [about styling in the svelte docs](https://svelte.dev/tutorial/styling).
+
+## SCSS
+
+Add a `lang` attibute to any style tags in your svelte components to use SCSS syntax.
+
+```svelte
+<style lang="scss">
+  div {
+    p {
+      color: purple;
+    }
+  }
+</style>
+```
+
+If you need to import an SCSS partial that will apply to your entire page -- like one of our house themes -- you can use the `:global` operator.
+
+```svelte
+<style lang="scss">
+  :global {
+    @import '@reuters-graphics/style-theme-eisbaer/scss/main';
+  }
+</style>
+```
+
+You may need to also import font-faces, specifically, if using our house themes:
+
+```svelte
+<style lang="scss">
+  @import '@reuters-graphics/style-main/scss/fonts/font-faces';
+  :global {
+    @import '@reuters-graphics/style-theme-eisbaer/scss/main';
+  }
+</style>
+```
+
+## CSS variables
+
+You can use inline CSS variables to use JavaScript values in your styles:
+
+```svelte
+<script>
+  let color = '#ff3e00';
+</script>
+
+<div style="--theme-color: {color}">
+  <p>the color is set using a CSS variable</p>
+</div>
+
+<style>
+  p {
+    color: var(--theme-color);
+  }
+</style>
+```