Skip to main content

​
Pages

A Page is a major destination in a Parable: a place where people read, explore, or finish a piece of work. Pages give a Parable its routes and navigation. A Page holds no data and no queries of its own. It arranges Panes, and the Panes own the values, logic, and styling. This split keeps destinations easy to rearrange, because moving a Pane between Pages never touches the data it shows. Parables are product experiences, so a Page must open fast: the data a reader sees first comes from stored Pipeline outputs, not from joins computed while they wait. Every Parable has a Home Page. Other Pages can sit beneath a Page to form a clear hierarchy. A Page has a small amount of layout code, a Perception that lists the Panes it renders, its own Policies, and a Palette. The Perception and Policies are part of the Page and versioned with it; the Palette is created with the Page and deleted with it. Its editor tabs are Programming, which shows its code beside its Perception, then Palette, Policies, Preferences, Plots, Panes, and Performance. A Page is composition only: its type is null, and its code may import only the Panes it declares and the runtime layout modules. Anything else, such as a chart, a control library or a company’s logo (BrandLogo), is refused at save with the import named; put that content in a Pane. Each Page keeps a permanent identity, so links and references survive a rename. Editing a Page follows the Parable’s Collaboration Mode: in Personal mode a save changes the Parable directly, and in Publishing mode it goes into Changes that are proposed and published. Who may edit is decided by the Parable’s participants and the Page’s Policies. Publishing compiles every Page; a syntax error or an unavailable import stops publication and leaves the published Version untouched. A Page that declares no Pane, or declares a Pane that does not exist, is reported as a finding when its Changes are published. Never delete and recreate a broken Page to clear an error: that creates a new identity and breaks links to the old one.
  1. Name the destination by the job a person completes there. Ask Ponder to state who arrives, what they must understand first, and where they go next. Save that job as the Page’s description, in one sentence: every Page needs one, and a save without it is refused. Keep Home useful. Add a child Page only when the content deserves its own route and title; use a Pane for a region inside the current Page, and a Package to group related Panes.
  2. Declare the Panes. Ponder adds each Pane the Page renders to its Perception, creating a Pane first when the Parable has none for that content. Values, configuration, controls, and queries belong in the Panes that own their meaning, never in page-local substitutes. Work down from what the Page shows first: any expensive query behind it should be a Pipeline its Panes read (see the Pipelines Power).
  3. Compose the layout. Ponder writes short layout code that places the declared Panes with ordinary elements and CSS, and adds no extraneous copy: no sentence that explains a Pane, says where a value came from, tells the reader they can change something, or repeats what a Pane already shows (see the Panes Power). Walk the reader’s path first, then the contributor, administrator, and support paths. Configuration and permission-recovery controls need a deliberate home in a Pane too, and a disabled one says why (see the Panes Power).
  4. Preview the route. Check navigation, loading, empty, and error states, keyboard use, both themes, and the XS to XL preview sizes. A Page with no Panes shows an add-a-Pane placeholder and can still be saved. Design a Platform Parable narrow-first: it also opens above the conversation in every Ponder header, in Ponder’s narrow column, so make each of its Pages work at S (390 px wide) first, then check the wider sizes.
  5. Design for every Provider. Every Parable is designed for full Provider coverage, however rare the Provider, and for any Workspace, whichever streams it turned on, with a useful state when none is connected, a useful state when some are, an empty state in every Pane, and a reason to connect more. On a Page with several visuals, each visual’s Pane wears ImproveParable on hover; on a Page with one visual or none, a Pane at the top holds one Improve this Parable band. The Home Page’s Perception declares the Parable’s Provider groups, and its content shows Populate this Parable while a Required to Populate group has fewer connected than its rule asks or no Provider has data yet (see the Populate, Perceptions and Panes Powers).
  6. Repair in place. When a Page fails to render, read the visible preview error and fix the Page or the Pane it declares within the same Changes.
  7. Give the Parable its description and its preview. They show on its sidebar card, with its name and mark. A Parable in Publishing mode publishes only when it has both. A Personal Parable does not need them. Make them when you build a Parable or change what it shows. Also make them when Prepare or a publish asks for them. Make them at Ponder Strong. If this turn runs at another level, start a Run at Ponder Strong in this Problem to do this step. If you cannot start one, ask the person to choose Ponder Strong and ask again.
    1. Read the Parable. Read its name, its current description, and its Pages, Packages, Panes and Plots with their descriptions. Read the Provider groups that its Home Page declares, and the outcome of this Problem. For a Lab, read its pages and its main components.
    2. Write the Parable’s one idea in one sentence: what a reader learns or does with it. List the three or four things that it shows. Use only what its Pieces show.
    3. Write the description. Keep the current description if it follows these rules. If it does not, write a new one.
      • Write one sentence of 25 words or fewer, in plain words that a new teammate understands.
      • Say what the reader sees or does. Do not start with “This Parable”, with “A dashboard”, or with a verb such as “Shows”.
      • Name kinds of data, such as calendar, mail, team chat or HR system. Never name a vendor, a product, a customer, a person, a model or a tool.
      • Do not write counts, dates or other values that change. Do not write plans. Do not claim what the Parable does not show.
      • If the Parable shows a fictional company’s data, start with the name of the Parable whose idea it shows, then the words “with a fictional company’s data:”.
      • Two good examples: “Where your teams’ working hours go, by category of work.” and “The four DORA keys and the throughput behind them.”
    4. Make the screenshot preview. Use the tool “Make a Parable’s preview”. It draws the first screen of one Page on a sample company’s data, in light and dark, and stores the two images. It never uses this Workspace’s data. If the Parable has a screenshot and its one idea did not change, keep that screenshot.
      • Choose the Page. Use Home, unless another Page shows the one idea better.
      • The picture is the whole first screen of the Page, about 960 by 600 pixels, with no crop. The card shows it about 450 pixels wide, so small text is not legible there. That is correct: the picture shows the shape of the Page, its main numbers and its charts.
      • The tool says which Version it drew. If that Version is older than the Changes in this Problem, tell the person that the preview shows the last deployed Version.
      • If the tool says that the sample company has no line or no Refresh of this Parable, the Parable has no screenshot for now. Do sub-step 6 and tell the person.
    5. Look at both pictures.
      • The tool names each Plot that returned no rows. If its Pane shows a large empty state, choose another Page.
      • Each Pane in the picture must show data or a useful state. A Pane that shows an error is a failure.
      • The picture must show only the sample company’s fictional names and values. If it shows a real person’s name, a real email address or a customer’s name, stop and tell the person.
      • If a check fails, choose another Page and make the preview again. If the tool refuses a Page, it says why.
    6. Draw the illustration preview too. Each Workspace shows either the screenshot or the illustration on its cards, so a Parable needs both. If the Parable has an illustration and its one idea did not change, keep that illustration. The illustration shows the Parable’s value, not its screens. Draw it as a product designer draws the hero image that announces a new product. A person who knows the subject must see what the Parable gives them in one look.
      1. Find the one idea. Write one sentence that says what a reader learns or decides with the Parable. Use its description and its Pages. For example: “The hours of a team split into kinds of work.” Draw only this idea.
      2. Choose one hero form that has the same shape as the idea. Do not draw a screen, a window, a table, a menu, a cursor, a chart with axes and values, or a copy of a Page.
        • One amount splits into parts, or parts join into one: bands that flow and split, or flow and join.
        • A level or a rating: a meter with a needle.
        • A day, a period or steps in order: an arc or a line from start to end, with the events on it.
        • Work that repeats: a ring.
        • One thing that connects many things: a hub with spokes.
        • Groups of people or things: clusters of discs.
      3. Choose three to six tokens. A token is a small flat sign that names one thing in the idea. Examples are a kind of work, a tool, a person or a release. Choose signs that a new teammate knows at once, such as a code bracket, a headset or a calendar page. Draw each token yourself in a box of 512 by 512 as two layers, in the style of a Font Awesome Sharp Duotone Solid icon: a back layer of simple shapes and a front layer of the main shape. Use only straight lines, arcs and square corners.
      4. Choose the colors from the list below. Give each color one meaning, such as one kind of work, one tier or one group. If a Pane of the Parable already gives a thing a color, use that color for that thing. Use five colors or fewer. Use the ink and the ground for all other parts.
      5. Lay out the picture.
        • The canvas is 1280 by 608 pixels. The card shows it about 480 pixels wide, so each size shows at three eighths. A 96 px tile shows at 36 px. A 48 px token shows at 18 px. A 4 px line shows at 1.5 px.
        • Make the hero form fill 60 to 75 percent of the height. Put it on the center, or on a golden section at x 489 or x 791.
        • Keep every form at least 64 pixels from each edge.
        • Put each token on a square tile of 92 to 108 pixels, with a token of 48 to 56 pixels. Put a person, a clock or a hub on a disc.
        • Make each band at least 24 pixels thick. Make each line that carries meaning at least 4 pixels wide.
        • Give tiles and discs a soft shadow. Draw bands, arcs, meters and lines flat on the ground.
      6. Draw it from this start file. Keep the palettes and the classes. For each color that you use, add its three variables to the three palette lines. Then copy the blue classes with the name of that color.
        • A tile is three shadow rectangles, then the face, then the token. Let x and y be the top-left corner of the tile, and s its side. The first shadow, class sh1, is at x-1 and y+4, s+2 wide and s+1 high. The second, class sh2, is at x-5 and y+10, s+10 wide and s+5 high. The third, class sh3, is at x-11 and y+18, s+22 wide and s+11 high.
        • A disc has the same three shadows as circles. Move the center down by 4, 10 and 18. Make the radius larger by 1, 5 and 10.
        • Place a token with transform="translate(X Y) scale(K)". K is the token size divided by 512. X is the center x minus half the token size. Y is the center y minus half the token size.
        • Put the back layer first, with class s. Put the front layer second, with class p.
        • On a white tile, give the token group the class of its color, such as blue. On a solid tile, give the face the class face-blue and the token group the class on-solid.
        • Draw a band from x0 to x1 with M x0 a0 C m0 a0 m1 b0 x1 b0 L x1 b1 C m1 b1 m0 a1 x0 a1 Z. a0 and a1 are its top and its bottom at x0. b0 and b1 are its top and its bottom at x1. m0 is x0 plus 42 percent of the distance. m1 is x1 minus 42 percent of the distance.
        • Draw the arc of a day from x0 to x1 over a line at y with M x0 y A rx ry 0 0 1 x1 y.
        • The colors, as light, deep, face, dark and dark face. In the dark lines, the deep variable is the dark color.
          • pink: #fa72b6, #c8448a, #eb65a9, #ff74b9, #ed64a9
          • orange: #f0845b, #bf582f, #e2774f, #ff8a5e, #e77449
          • gold: #c59b51, #986f21, #b88e44, #fac25b, #c18b13
          • green: #67b25f, #3c8635, #5ba553, #6ec466, #52a74a
          • teal: #57b19c, #248471, #49a490, #60d8bc, #21a78d
          • blue: #739bf5, #4f73ca, #6b92ec, #739bf5, #6b92ec
          • red: #dd496c, #d33f64, #dd496c, #dd496c, #dd496c
          • stone: #a5a194, #7a766a, #989588, #ddd8c4, #9a9582
          • magenta: #a11a5c, #a11a5c, #a11a5c, #ff50ad, #fe50ad
          • cyan: #53aebc, #1f8290, #45a1af, #5bd2e3, #1ba3b4
        • Write no words, numbers, letters or logos.
        • Use only the elements svg, g, defs, style, title, desc, pattern, clipPath, mask, rect, circle, ellipse, line, polyline, polygon and path. Refer to nothing outside the file. Keep the file under 32 KB.
      7. Check the illustration before you save it.
        • One idea: a person who knows the subject can say what the Parable is about from the picture alone.
        • Value: the picture shows what the reader gets. It does not show how the Parable looks.
        • No interface: the picture has no window, button, table, menu, cursor or text.
        • Card size: each token is 48 px or more. Each line that carries meaning is 4 px or more.
        • Light and dark: each color comes from a variable that the three palette lines all set. A white token is only on a solid face.
        • Honest: the picture shows only what the Parable shows. It shows no real value, name or logo.
        • Three examples. AI ROI: a clock pours bands of hours into four tiles, one for each kind of work. Software Delivery: a meter runs from Low in red to Elite in green. Its needle points to Elite, and the weekly throughput rises around its rim. Work Activity: a day arcs from sunrise to night, with the tools on it in order. The day’s line marks the span from the first activity to the last.
    7. Save the description and both previews in one call to “Rename a Parable or change how it is labelled”. Send the two image ids that the preview tool gave as previewLightSha256 and previewDarkSha256, and send the illustration as previewSvg. A save of one kind of preview does not change the other. In Publishing mode, add the id of this Problem’s Changes. If this Problem has no Changes, open them first. If the server refuses a preview, the answer names the rule. Correct only that rule and save again.
A good Page has one clear job and a name that says it. A reader can reach it and leave it by keyboard and on a narrow screen, every declared Pane renders quickly on the Workspace’s full data, and missing or denied data shows a useful state instead of a blank area. Every time on it reads in the reader’s time zone and clock, such as “12:31pm ET”: a Page shows no time of its own, and its Panes format each one with formatTime and formatDateTime (see the Panes Power). Repair controls stay reachable while the preview shows an error. Check the result by saving, opening the Page at more than one preview size, and confirming its Changes report no missing Pane reference. A Pane preview inside the conversation uses captured data and cannot run live SQL or save settings, so confirm data-dependent behavior in the running Parable. An attractive static arrangement is not a finished destination. Related Powers: Panes, Pipelines, Packages, Perceptions, Palettes, Policies, Publishing. Find each by its title; do not guess stored names.